NetBeans Developer Faq

NetBeans is a modular application. That means it is composed of pieces, which are discovered at runtime. Some of those pieces may even be downloaded and installed or uninstalled at runtime.

A module is a library. It is a Java JAR (Java ARchive) file which contains some classes.

NetBeans is a Java application. It has a very small core runtime which knows how to find the modules that make up the application (the launcher passes a list of directories - these are commonly called clusters - which contain module JAR files and some XML metadata about them).

All real functionality of the NetBeans IDE or any NetBeans-based application is implemented as modules.

A module JAR contains some additional entries in its META-INF/MANIFEST.MF file, which tell NetBeans about the module - its name, its version, etc.

One distinction about NetBeans modules, as opposed to just working with JAR files on your classpath is that the NetBeans runtime enforces dependency management between modules - to call code in another module from yours, your module must declare a dependency on the other module.

Another significant distinction is that a module can specify which (if any) packages it makes visible to modules that depend on it - so it is possible to have Java packages in a module's JAR file which are visible only to other classes within that JAR file. That, in effect, extends Java's class visibility-scoping rules (public, protected, private, package-private) to include public only within this JAR file.

The NetBeans Platform has a learning curve. The goal of this FAQ is to get you over the basic humps quickly. Being proficient does not necessarily mean knowing everything there is to know. It means being able to find what you need to know quickly when you need it. Here are some pointers.

Javadoc

The reference documentation for all of NetBeans APIs can be found on the web here: http://bits.netbeans.org/dev/javadoc/index.html.

If you want a local copy of it, you can either download it from the update center, or build it from your source checkout

cd $NB_SRC_ROOT
ant build-javadoc

Using the Javadoc

Notice the list of APIs in the upper left in the javadoc. These restrict the list of classes to a single API. /Also notice the link that says _javadoc_ next to each API name. It's important! This links to the overview page for each API. That page contains a list of changes, an architecture description, and other very useful stuff!/

NetBeans Tutorials

There are a huge number of tutorials. Do at least some of them - step by step.

FAQs

There is a huge Frequently Asked Questions for Module Developers list. It is worth bookmarking.

Getting the Source Code

Some people claim that they should never need to look at source code - documentation should suffice. That's just silly. The NetBeans codebase is a treasure-trove of examples of how to do things.

Since the end of January 2008 the NetBeans sources are stored in Mercurial repository at hg.netbeans.org.

You can see useful documentation about Mercurial and also about its specifics for NetBeans repository in HgMigrationDocs wiki topic. If you are already familiar with Mercurial you cat go directly to HgHowTos topic.

You will end up with a large number of directories representing top-level NetBeans projects. Most of them will be openable as projects in NetBeans.

Here's how to build it.

The build of NetBeans will be created in nbbuild/netbeans.

How To Find Useful APIs

See the tasks to APIs faq for a list of common tasks and what APIs you will want to use to accomplish those tasks.

Get the NetBeans Platform Examples

There are a large number of samples. Many of these correspond to the tutorials.

Two full blown NetBeans Platform applications are provided as samples in NetBeans IDE. Look in the Samples category in the New Project dialog and you will find the FeedReader sample and the Paint sample, for both of which there are tutorials describing how to create them from scratch.

You can find several other samples in the module platform in main/misc repository at hg.netbeans.org. They are in the platform/samples/ subdirectory. The platform/samples/ folder can be browsed online here.

Build Platform from Sources

First get platform sources from download page or use Hg client as described in HgHowTos.

To build platform run

cd $NB_SRC_ROOT
ant build-platform

Mining the NetBeans Source Code for Examples

For most things you will need to do, there is some module that does something similar already. For example, say that you want to show a window that shows the contents of some random directories on disk or some registry of objects your module creates. The core/favorites module provides the Favorites window which does exactly this. A bit of intuition and a willingness to open a couple of projects is all it takes to find examples of many things. Often a good place to start is simply to open the source for a class you think you want to use and run Find Usages on it.

Use the Mailing Lists

If you have questions, the best place to go is the developer mailing list. Click this link to subscribe.

You can also browse the archives online, but actually joining the mailing list is the best way to get (and give) help.

Note: dev@platform.netbeans.org was formerly dev@openide.netbeans.org - older archives can be found on Nabble and via a newsreader by going to news://news.gmane.org.

Ask questions, and when you can answer them, do that too. There is a very healthy and helpful community there.

First, make sure you have Mercurial installed on your machine, along with its requirements such as Python.

Then, from the command line, you run

hg clone http://hg.netbeans.org/main/
cd main

to get the full Platform and IDE sources. If you also want the contrib/ modules:

hg clone http://hg.netbeans.org/main/contrib/

To build, simply run ant. The build will appear in nbbuild/netbeans/.

More info about using Mercurial with NetBeans sources...

(as of June, 2010)

1. Go to the nightly build download site:

   http://bits.netbeans.org/dev/nightly/

2. Click the link for the build you want.

3. You will be shown an index page where you can find a link to the folder with ZIP archives of binary builds and sources.

4. Click the link or add "zip/" to the end of the URL in your browser's address bar manually and hit enter. In other words, the complete URL might look like this:

   http://bits.netbeans.org/dev/nightly/2010-06-11_00-01-15/zip/

5. There are about a dozen links on that page. The one you want begins with "netbeans-trunk-nightly" and ends with "-src.zip" Click that link to download the source archive.

Here is a list of common things people need to do, and a very short description of how you do them. From here, use the Javadoc and tutorials to get more information.

I want to ...

Show my component in the main window

Use the Window System API. You will want to create a subclass of TopComponent, a JPanel-like class, and call its open() method to show it.

Write to the output window

Use the I/O API. Call IOProvider.getDefault().getInputOutput("Something"). The object returned has getters for standard output, standard error and input streams which write to and read from a tab in the output window.

Show a Tree, List or other control with a list of some objects

Use the Nodes API to create a hierarchy of Node objects, each representing one object in your data model. Then use the Explorer API to show the Nodes - it contains tree, list, table, combo box and other controls which can show a hierarchy of Nodes. Nodes are very easy to add popup menus to, decorate with icons and html-ized display names, etc. and are a lot less work than using Swing components directly. See also the Nodes API Tutorial.

Provide an Editor for a particular kind of file

Use the new File Type template. You will end up using the Data Systems API (DataObject, DataLoader, etc.) and Nodes API primarily, plus the Filesystems API for accessing and parsing the file. The Text API provides general support for creating editors for files.

Add a menu item to the main menu

No specific NetBeans APIs are needed - you can just create a subclass of Swing's AbstractAction, and register it in your modules layer.xml file. Or, use the new Action template in the IDE to generate a subclass of SystemAction for you and all the registration code, and fill in the action-performing logic.

Show content in the Navigator window when a file of a certain type is selected

Use the Navigator API to create a navigator panel provider; you then somehow parse the file and can create any component you want to show in the Navigator, and populate it with whatever you want.

Show a progress bar

Use the Progress API - call ProgressHandleFactory to create a ProgressHandle for you. That is an object with methods for setting the progress, status text, number of steps, etc. and is fairly self-explanatory. Remember to make sure the code showing progress is not running in the AWT Event thread.

Set the main window's statusbar text

Use the UI Utilities API. Simply call StatusDisplayer.getDefault().setStatusText().

Allow other modules to register objects and then find those objects dynamically at runtime

Define a folder in the System Filesystem in the XML layer file of your module. Other modules can register instances of whatever class you specify by declaring .instance files in their own XML layer files. You can find them at runtime using Lookups.forPath("path/to/my/folder") to get an instance of Lookup that you can query for these objects.

Save some settings persistently

Use the Utilities API, specifically NbPreferences - which is just an implementation of the JDK's Preferences API which stores things in the user's settings directory rather than globally. It's just like using standard JDK Preferences.

Run some code at application startup/shutdown

Use the Module System API. Implement a subclass of ModuleInstall and override restored(), close(), etc. Remember it is best to avoid running code on startup unless you really need to.

Add a Panel to the Options dialog

Use the Options API, implementing OptionsCategory to define the category in the dialog and OptionsPanelController to manage the UI component.

Find/listen to/manipulate the set of open projects

Use the Project UI API, specifically OpenProjects.

Create a graph editor such as the Mobility Pack uses

Use the Visual Library, which builds on top of Swing to make animated, graph-oriented UIs easy to build. More info, tutorials and webcasts can be found in the platform.netbeans.org/graph project.

Yes. The license is very non-restrictive. For details, see the license.

There is a naming convention for APIs in NetBeans. Generally when a new API is introduced, it will be under development and not stable for a while. During that period, the naming convention for its package is org.netbeans.modules.something.api. So, if you rely on an API with a name like that, your code could break. Generally it is the responsibility of the author of that API to refactor all modules in NetBeans source repository when the API graduates to "official" status.

An official API uses the naming convention org.netbeans.api.something. APIs named this way should remain backward compatible.

netbeans.exe is the Windows launcher for NetBeans. Basically it assembles the class path string for starting up NetBeans, passes the command line arguments, etc., and launches Java with those arguments.

The main reasons for the exe are:

• Start NetBeans without a console window opening as well as the main window
• Windows shell quoting is inconsistent across versions of Windows
• On some versions of Windows, command line length is limited to a shorter length than is sometimes needed for all the command-line arguments that should be passed to java
• Provide a thing you can double click that has the correct icon

It's nothing terribly exciting, it's just a small C++ app; the sources are in ide/launcher.

Up to NetBeans 6.5 there were actually two executables - nb.exe and netbeans.exe. netbeans.exe will suppress the console window (so you won't see any logging on the command line); nb.exe will show the command line. Under the hood, netbeans.exe invokes nb.exe (so don't rename it).

Starting with NetBeans 6.7 the following changes in the Windows launcher were introduced - WinNB67Launcher.

There is no separate set of Javadoc for the NetBeans Platform. However, as the Platform is just a subset of the IDE, the Javadoc for the IDE will apply.

You can browse the Javadoc online (this link always points to the latest development version).

You can also download the Javadoc for a particular NetBeans release:

1. Go to the nightly build download site: http://bits.netbeans.org/dev/nightly/

2. Click the link for the build you want.

3. Add "zip/" to the end of the URL in your browser's address bar and hit enter. In other words, the complete URL might look like this: http://bits.netbeans.org/dev/nightly/2010-06-11_00-01-15/zip/

5. There are about a dozen links on that page. The one you want begins with netbeans-trunk-nightly and ends with -javadoc.zip; click that link to download the Javadoc archive.

Finally, you can go to the update center (Tools > Plugin Manager) in the NetBeans IDE and request the NetBeans API Documentation module, which bundles Javadoc matching your IDE release. Use Help > Javadoc References (View > Documentation Indices in NetBeans 5.x) to see the overview pages for API sets currently used by your open projects. The IDE should also automatically display this Javadoc in code completion popups.

Applies to: NetBeans 5.x, 6.x, 7.x

Platforms: all

In versions of NetBeans prior to 6.0, two major products were available for download: the IDE and the platform. The platform is the foundation on which the IDE is built, or looking at it another way, the platform is what's left over when you remove all the IDE features from the IDE. At any rate, the platform provides user interface components, build scripts, declarative configuration and many other features that can save you a lot of time and effort in creating your own application.

Because platform-based applications are themselves platforms that can be extended, the IDE can also be extended just as the platform can. Since you can remove features from a platform as well as add new ones, the availability of the platform and IDE let you choose between starting small and adding on (platform) or starting large and removing things (the IDE). Some feel the latter approach is better and even facing such a choice can be confusing to new users. If you're a new user, you'd do well to heed this advice and just use the IDE as a platform. It works just as well and is a lot less trouble.

But if you're still here, you may be asking where is the platform? Binary distributions of the platform are not being made available from version 6.0 onward (and issue #124372 filed to bring them back was closed without any reasonable explanation). So if you want a platform binary, you'll have to create one yourself.

nbbuild

   ant -Dcluster.config=platform build-platform

If you're using Java 6, you'll need to add an extra property:

   ant -Dcluster.config=platform build-platform -Dpermit.jdk6.builds=true 

But be aware that it is not guaranteed to build under Java 6 due to language changes or compiler bugs. It is unlikely you will encounter such a problem in the platform build, though it has certainly been known to happen in the IDE build. If you find something that won't compile under Java 6 but does compile under Java 5, file a bug report (preferably with a patch) about it so it can be corrected. Meanwhile, you can use Java 5 to compile -- even when Java 6 is first in your path -- by using the nbjdk.home system property to point to your Java 5 installation:

   ant -Dcluster.config=platform build-platform -Dnbjdk.home=c:/devtools/jdk/jdk-1.5.0_u15

netbeans

It's also possible to create platforms based on a different subset of the NetBeans project. Hints for doing this can be found here:

• Working with NetBeans Sources

Why would you want to build your application on a separate platform instead of the IDE as a platform?

Using the IDE is certainly easier, but there are inherent dangers associated with developing against your own IDE as the platform. In particular, another developer on your team may have a different version of the IDE, have different modules/clusters installed or even have simply named the platform something different in the Platform Manager. This can result in a broken build or the introduction of unwanted features. It also makes doing an automated build, such as through Hudson or CruiseControl, far more difficult.

If you want to avoid these problems, you can check the platform you want to build against into source control and then set the netbeans.dest.dir and harness.dir properties in your suite's nbproject/platform.properties file to point to the platform and harness, respectively. Building from a known version checked out from source control avoids these problems and makes it possible to historically reproduce any build. I show example values for these below:

# NOTE: You must remove the nbplatform.default line which might already exist in this file.
# Also note that editing the properties of your suite via the suite customizer (dialog)
# can add that line back in, so you'll need to watch for this and delete it again in this case.

# where the suite is located; you don't need to change this.  It exists 
# to allow us to use relative paths for the other values
suite.dir=${basedir}

# the path to the NetBeans IDE or platform binary we want to build against 
# (e.g. if building against the IDE, this points to the directory created when 
# you unpack the IDE zip file).  this example assumes your platform directory 
# is parallel to the suite directory, but you can change it to suit your needs
netbeans.dest.dir=${suite.dir}/../platform

# path to the build harness you want to use.  This is typically in the 
# harness subdirectory of your platform, but you could point to a directory
# containing customized build scripts if you want to.
harness.dir=${netbeans.dest.dir}/harness

Update for NBM projects generated by NetBeans 6.7 and later

If you have generated your projects in IDE version 6.7 and later, you have to modify the above described method slightly (6.5.1 and earlier projects compile against newer platform/harness without changes). You can distinguish "newer" project by the presence of cluster.path property in nbproject/platform.properties file or simply by the fact that an attempt to build a suite with above described platform.properties results in error:

.../harness/suite.xml:60: When using cluster.path property, remove
netbeans.dest.dir, enabled.clusters and disabled.clusters properties
from platform config, they would be ignored.

In such case you have to replace netbeans.dest.dir, enabled.clusters and disabled.clusters properties with new property cluster.path, e.g.:

# NOTE: You must remove the nbplatform.default line which might already exist in this file.
# Also note that editing the properties of your suite via the suite customizer (dialog)
# can add that line back in, so you'll need to watch for this and delete it again in this case.

# where the suite is located; you don't need to change this.  It exists 
# to allow us to use relative paths for the other values
suite.dir=${basedir}

# just a helper property pointing to the same location as netbeans.dest.dir did before;
# Referenced only in this properties file, has no meaning for NB harness.
platform.base=${suite.dir}/../platform

# Give a name to the platform at the relative path and define its location
# using the platform.base property we set above. You can change the value  
# ('myplatform') to something more descriptive (like 'nb68'), but you
# must then change the name of the second property (e.g. from 
# nbplatform.myplatform.netbeans.dest.dir to nbplatform.nb68.netbeans.dest.dir)
nbplatform.active=myplatform
nbplatform.myplatform.netbeans.dest.dir=${platform.base}

# classpath-like list of absolute or relative paths to individual clusters 
# against which you want your suite to build; Note that you can use 
# "bare", i.e. not numbered cluster names, which simplifies later transitions
# to newer version of the platform. E.g:
cluster.path=${platform.base}/platform:\
     ${platform.base}/ide:\
     ../otherSuite/build/cluster

# path to the build harness you want to use.  This is typically in the 
# harness subdirectory of your platform, but you could point to a directory
# containing customized build scripts if you want to.
harness.dir=${platform.base}/harness

Note that the content of cluster.path is not limited to clusters from NB platform, you can add clusters from other suites, standalone modules, etc. This allows to reuse non-platform modules in several RCP apps. More on module reuse here, other details about setting up cluster.path can be found in harness/README.

Update for NBM projects generated by NetBeans 7.0 and later

Now the the platform can get downloaded automatically with some minor tweaks! This is great for usage in Continuous Integration servers like Hudson/Jenkins.

See here for more details.

Some automation anyone?

The above process is basically manual so here are some stuff I developed to automate the process:

Update the development environment

The following allows to update the development environment mentioned above that should be part of version control. (i.e. to make it work from Hudson for example)

• Add a xml file in the suite's root (referred as preparation.xml from now on)

Hare are its contents:

<?xml version="1.0" encoding="UTF-8"?>
<project name="XXX-Preparation" basedir=".">
    <description>Prepares the environment to build the module suite XXX.</description>
    <!--Don't modify this file unless you know what you are doing-->
    <property name="ant-contrib-filename" value="ant-contrib-1.0b3.jar"/>
    <property file="nbproject/project.properties"/>
    <property file="nbproject/platform.properties"/>
    
    <target name="update-platform" depends="init-netbeans">
        <for list="${cluster.path}" delimiter=":" param="cur" trim="true">
            <sequential>
                <add-core-module module="@{cur}"/>
            </sequential>
        </for>
    </target>

    <target name="unzip-compilation-env" depends="init-netbeans, init-hudson">
        <!--Hudson needs to run this task first as it gets the core modules as zip from version control-->
        <for list="${cluster.path}" delimiter=":" param="cur" trim="true">
            <sequential>
                <expand-module module="@{cur}"/>
            </sequential>
        </for>
    </target>

    <target name="update-env" depends="init-netbeans, init-hudson" description="Update the Netbeans core modules used to compile/run OIT">
        <!--Make sure that any recently added module using the IDE is also included.
        Fix it to the proper format.-->
        <mkdir dir="../netbeans/"/>
        <propertyregex property="cluster.path"
               input="${cluster.path}"
               regexp="nbplatform.active.dir"
               replace="platform.base"
               global="true"
               override="true"/>
        <replaceregexp file="nbproject/platform.properties"
                       match="nbplatform.active.dir"
                       replace="platform.base"
                       byline="true"
                       flags="g,s"/>
        <pathconvert pathsep="\;" property="folders_temp">
            <dirset dir="../netbeans/">
                <include name="*/**"/>
                <!--ignore svn and cvs files-->
                <include name="**/.svn"/>
                <include name="**/.svn/**"/>
                <include name="**/CVS"/>
                <include name="**/CVS/**"/>
                <!--Exclude the nb-plugins folder-->
                <exclude name="nb-plugins/**"/>
                <!--Exclude the root folder-->
                <exclude name="../netbeans"/>
            </dirset>
        </pathconvert>
        <antcall target="update-platform"/>
        <antcall target="unzip-compilation-env"/>
    </target>

    <macrodef name="expand-module">
        <attribute name="module"/>
        <sequential>
            <delete dir="@{module}"/>
            <unzip src="@{module}.zip" dest="@{module}"/>
        </sequential>
    </macrodef>

    <macrodef name="add-core-module">
        <attribute name="module"/>
        <sequential>
            <if>
                <equals arg1="@{module}" arg2="../netbeans/nb-plugins"/>
                <then>
                    <echo>Adding custom module @{module}</echo>
                    <available file="@{module}" type="dir" property="customdir.exists"/>
                    <if>
                        <equals arg1="${customdir.exists}" arg2="true"/>
                        <then>
                            <zip destfile="@{module}.zip" basedir="@{module}" update="true"/>
                        </then>
                    </if>
                </then>
                <else>
                    <length string="@{module}" property="@{module}.length.module" />
                    <substring text="@{module}" start="12" end="${@{module}.length.module}" property="new.module"/>
                    <echo>Adding netbeans core module ${new.module}</echo>
                    <mkdir dir="../netbeans/${new.module}/"/>
                    <delete file="../netbeans/${new.module}.zip"/>
                    <delete includeemptydirs="true">
                        <fileset dir="../netbeans/${new.module}/" includes="**/.*" defaultexcludes="false"/>
                    </delete>
                    <zip destfile="../netbeans/${new.module}.zip" basedir="${netbeans.home}\..\${new.module}" update="true"/>
                </else>
            </if>
        </sequential>
    </macrodef>
    
    <scriptdef name="substring" language="javascript">
        <attribute name="text" />
        <attribute name="start" />
        <attribute name="end" />
        <attribute name="property" />
     <![CDATA[
       var text = attributes.get("text");
       var start = attributes.get("start");
       var end = attributes.get("end") || text.length;
       project.setProperty(attributes.get("property"), text.substring(start, end));
     ]]>
    </scriptdef>

    <target name="check-env" depends="getAntContribJar">
        <condition property="isNetbeans">
            <not>
                <isset property="Hudson"/>
            </not>
        </condition>
    </target>

    <target name="getAntContribJar">
        <fileset id="ant-contrib-jar" dir="${suite.dir}/tools">
            <include name="ant-contrib-*.jar" />
        </fileset>
        <pathconvert property="ant-contrib-jar" refid="ant-contrib-jar" pathsep="," />
        <basename property="ant-contrib-filename" file="${ant-contrib-jar}"/>
    </target>

    <target name="init-netbeans" depends="check-env" if="isNetbeans">
        <echo>Configuring ant-contrib for Netbeans use...</echo>
        <property name="ant-contrib-loc" value="${suite.dir}/tools/${ant-contrib-filename}"/>
        <available file="${ant-contrib-loc}" property="ant-contrib.present"/>
        <fail unless="ant-contrib.present" message="The ant-contrib jar doesn't exist at: ${ant-contrib-loc}, can't build. Check your settings!" />
        <!--We are in not Hudson-->
        <taskdef resource="net/sf/antcontrib/antcontrib.properties">
            <classpath>
                <pathelement location="${ant-contrib-loc}"/>
            </classpath>
        </taskdef>
    </target>

    <target name="init-hudson" depends="check-env" unless="isNetbeans">
        <echo>Configuring ant-contrib for Hudson use...</echo>
        <!--Import Hudson environment variables-->
        <property environment="env"/>
        <property name="ant-contrib-loc" value="${env.ANT_HOME}/lib/${ant-contrib-filename}"/>
        <available file="${ant-contrib-loc}" property="ant-contrib.present"/>
        <fail unless="ant-contrib.present" message="The ant-contrib jar doesn't exist at: ${ant-contrib-loc}, can't build. Check your settings!" />
        <!--Define it. For some reason the approach in init-netbeans doesn't work in Hudson.-->
        <taskdef name="for" classname="net.sf.antcontrib.logic.ForTask">
            <classpath>
                <pathelement location="${ant-contrib-loc}"/>
            </classpath>
        </taskdef>
        <taskdef name="propertyregex" classname="net.sf.antcontrib.property.RegexTask">
            <classpath>
                <pathelement location="${ant-contrib-loc}"/>
            </classpath>
        </taskdef>
        <taskdef name="if" classname="net.sf.antcontrib.logic.IfTask">
            <classpath>
                <pathelement location="${ant-contrib-loc}"/>
            </classpath>
        </taskdef>
        <taskdef name="math" classname="net.sf.antcontrib.math.MathTask">
            <classpath>
                <pathelement location="${ant-contrib-loc}"/>
            </classpath>
        </taskdef>
        <taskdef name="var" classname="net.sf.antcontrib.property.Variable">
            <classpath>
                <pathelement location="${ant-contrib-loc}"/>
            </classpath>
        </taskdef>
    </target>
</project>

Here's a sumary of the targets and what they do:

• init-netbeans/init-hudson: Configures the ant-contrib lib used in other tasks. For some reason Hudson doesn't work with the init-netbeans approach.
• getAntContribJar: Looks in the suite's tools folder for the ant-contrib jar file. This file name is then used by other tasks
• check-env: Basically to decide if we're in Netbeans or in Hudson. While in Hudson just pass the -DHudson=true parameter to the ant job. Having this variable set (not the value) tells this task that we are in Hudson.
• update-env: The task to call. This one updates the cluster.path values in nbproject/platform.properties to set it up as mentioned in this FAQ. Why you might ask? This just takes care of updating any later addition of a module via using Netbeans and converts it to the format discussed in this FAQ. Basically no need to manually modify the nbproject/platform.properties file after the initial change!
• update-platform: This will grab the current's IDE modules defined in cluster.path and zip them in a netbeans folder parallel to the suite's root folder. No need to do it manually!
• unzip-compilation-env: this unzips the zips created in the above task to their proper place.

Keep in mind that after making the changes proposed earlier in this FAQ the project won't work (i.e. build, run, etc) if the environment is not set.

That's the reason of doing all this in another xml file. Attempting any of this from the suite's build file won't work since you are messing with the platform files it is working from.

Notes:

• Make sure to have an ant-contrib file in <suite's root>/tools folder for the above to work.
• Current release of ant-contrib has an error. To fix it unpack the jar and add this entry to the net/sf/antcontrib/antcontrib.properties file in the Logic tasks section:

for=net.sf.antcontrib.logic.ForTask

See also:

• Can I sign NBMs I create? for tasks to sign all your nbm files
• How can I customize the build process? To add any custom task you might have to the build process.

By default, a NetBeans Platform application will use the developer's copy of the IDE as the platform. This is certainly easy, but there are also drawbacks to using the current IDE as a platform. With that in mind, lets check out, and reference our own copy of the NetBeans source code. This way we can also use breakpoints to step through the NetBeans source code, make changes, and create patches!

At a high level the steps are as follows. First get the NetBeans source code checked out. This part is interesting because what you end up with is a complete copy of the NetBeans source repository on your local file system. The second thing you need to do is build the NetBeans platform using the source repository that you just checked out. This is important because without building the platform you will not have the dependencies required by the platform modules. The next step is to create a new platform reference. Of course the platform to reference will be the one that you just checked out and built. Then finally, in your module suite's project properties, select the platform reference that you just created.

So, in more detail then...

1. Check Out NetBeans Source Code

First get the source code from the Mercurial repository. In the following example the source code is checked out to a local ~/netbeans-repository/ directory. In this example the tilde is used to represent the home directory of your file system.

So far, so good, but you still need to build the source code so that you have a complete NetBeans Platform, along with all the jar dependencies.

2. Build The NetBeans Source

Building the NetBeans source is very easy, and very satisfying to watch! Just open up your favorite terminal client and navigate to your local repository.

cd ~/netbeans-repository/main/

Set the available memory that Ant can use:

set ANT_OPTS=-Xmx256M

(or on Unix, export ANT_OPTS=-Xmx256M)

Then simply run ant.

ant -Dpermit.jdk6.builds=true

Note, I am choosing to build NetBeans using JDK1.6 so I have to explicitly tell NetBeans that I understand that only JDK1.5 is supported. As of NetBeans 6.9, NetBeans is built with JDK 6, and this flag is no longer needed.

3. Create A New Platform Reference In NetBeans

In order to work with the NetBeans platform that you just built it needs to be added as a platform in the IDE.

1. Click Tools -> NetBeans Platforms (note that the menu item name varies slightly in older versions)

2. Click the "Add Platform..." button in the lower right

3. Locate the platform binary and click OK. In this example the proper path is ~/netbeans-repository/main/nbbuild/netbeans/.

4. You can associate sources and javadoc for this platform using the respective tabs in the platform manager

5. You can also choose which version of the build scripts you want to us on the Harness tab. You'll usually want to use the version corresponding to that platform.

4. Reference The New NetBeans Platform

Now just select the platform in your module suite's Project Properties. There you will see a Netbeans Platform dropdown box where you can select the platform that you set up.

Note: I did have to go through and resolve some of the cluster dependencies. That just means that I had to check the dependencies that Netbeans said that other modules needed. Once you get this far it will be very obvious what to do.

Appendix: NetBeans Platform And Using JDK1.6

In order to use JDK1.6 with the Netbeans source code we need to tell the Netbeans platform that we understand that only JDK1.5 is supported. What you need to do is create a "user.build.properties" file and put it in the nbbuild directory.

touch ~/netbeans-repository/main/nbbuild/user.build.properties

Inside the user.build.properties file put the following line.

permit.jdk6.builds=true

This tutorial applies to: versions 6.7 and earlier of the NetBeans Java IDE.

If you've unpacked or checked out the NetBeans sources, you'll see more then 600 directories. Almost every one of these directories is a module. Although the directory names indicate the purpose of each, sometimes it's still not clear what each does.

The easiest way to find out about a module in the source tree is to open its manifest file, then look for the entry named OpenIDE-Module-Localizing-Bundle. The file referenced there (located deeper inside the module directory) typically contains the module's display name, descriptions and other information. You could automate the extraction of these values through a simple shell or perl script, but for your convenience, I've included the short description of each one below:

ant.browsetask=Adds an Ant task <nbbrowse> to run inside NetBeans to open a web browser.
ant.debugger=Enables debugging on Ant scripts.
ant.freeform=Special project type for projects with pre\u00EBxisting Ant scripts.
ant.grammar=Code completion for textual editing of Ant scripts.
ant.kit=Support for Ant build scripts.
antlr=Antlr Developement Libraries
api.debugger=Enables debugging with the AAA debugger implementation.
api.debugger.jpda=JPDA Debugger API
api.debugger=NetBeans Debugger APIs.
api.java.classpath=Classpath APIs
api.java=APIs for Java development support modules
api.mobility=Mobility Core API module.
api.progress=Task progress visualization APIs.
apisupport.apidocs=Local documentation for the NetBeans APIs.
apisupport.feedreader=Feed Reader Application
apisupport.feedreader=Wrapper for JDOM library
apisupport.feedreader=Wrapper for ROME Fetcher Library
apisupport.feedreader=Wrapper for ROME Library
apisupport.feedreader=Bundles a demonstration application using the NetBeans Platform.
apisupport.harness=Lets you build external plug-in modules from sources.
apisupport.paintapp=Sample NetBeans platform application.
apisupport.project=Defines an Ant-based project type for NetBeans modules and module suites.
apisupport.project=Some short description
apisupport.refactoring=Additional refactoring support for NetBeans module projects.
api.visual=Visual Library API
api.web.webmodule=APIs for web module development support modules.
api.xml=This module contains XML tools API and SPI.
applemenu=Enables proper support for the Apple \
asm=Assembler support
autoupdate.services=Support for searching for module updates on Update Center and for downloading and installing modules
autoupdate.ui=Supplies UI of Auto Update Services
beans=Support for creating JavaBeans(TM) components.
bpel.core=BPEL Core.
bpel.debugger.api=Enables debugging on BPEL files.
bpel.debugger.bdi=BPEL Debugger RMI.
bpel.debugger=BPEL Debugger.
bpel.debugger.ui=BPEL Debugger UI.
bpel.editors.api=BPEL Editors API.
bpel.editors=BPEL Editors.
bpel.help=BPEL Help.
bpel.kit=BPEL development support.
bpel.mapper=BPEL Mapper.
bpel.model=Object model for BPEL 2.0.
bpel.project=Composite Application Base Project.
bpel.project=BPEL Project.
bpel.refactoring=BPEL Refactoring.
bpel.samples=BPEL Samples.
bpel.validation=BPEL Validation.
classfile=Provides read-only access to Java class files.
clearcase=Clearcase Versioning System
cnd.antlr=Supports the C/C++ Code Model - contains ANTLR parser generator library
cnd.api.model=API that represents C/C++ code
cnd.api.project=A bridge between C/C++ project system and C/C++ code assistance
cnd.apt=APT presentation for files with preprocessor
cnd.callgraph=C/C++ Call Graph
cnd.classview=C/C++ Class View
cnd.completion=Code completion for C, C++, and Fortran languages
cnd.debugger.gdb=Supports debugging of native programs with gdb
cnd.discovery=C/C++ Discovery API/SPI
cnd.dwarfdiscovery=C/C++ Dwarf-based Discovery Provider
cnd.dwarfdump=Reading dwarf debugging information
cnd.editor=C/C++ Editor
cnd.folding=C/C++ APT-based Folding
cnd.gotodeclaration=C/C++ Go To Declaration
cnd.highlight=Provides error highlighting for the C/C++ languages.
cnd.kit=C/C++ development support.
cnd.lexer=Lexical analysis for C/C++ Pack languages
cnd.makeproject=Supports C/C++ projects
cnd.modeldiscovery=C/C++ Model-based Discovery Provider
cnd.modelimpl=Implementation of C/C++ Code Model API
cnd.model.services=Code Model Services
cnd.modelui=UI for Implementation of C/C++ Code Model API
cnd.modelutil=Miscellaneous utilities used by C/C++ Code Model
cnd.navigation=C/C++ Code Navigation
cnd.qnavigator=Provides navigator content for C/C++ files
cnd.refactoring=C/C++ Experimental Refactoring
cnd.remote=Support remote developement
cnd.repository.api=Api for the CND repository
cnd.repository=Persistence mechanism for Code Assistance features
cnd=Enables development of C and C++ programs in the IDE
cnd=Enables editing of C, C++, and Fortran files in the IDE.
cnd.utils=C/C++ Utilites
collab.channel.chat.java=Support for developer-friendly instant messaging chat (Java).
compapp.casaeditor=Composite Application Service Assembly editor.
compapp.configextension=JBI descriptor configuration extensions.
compapp.help=Composite Application Help Topics.
compapp.kit=Composite application development support.
compapp.manager.jbi=Composite Application JBI Manager.
compapp.projects.base=Composite Application Project.
compapp.projects.jbi=Composite Application JBI Project.
compapp.projects.wizard=Supplies the generic wizard interface for CAPS projects in the IDE.
core.execution=Implementation of the Execution engine.
core.ide=Makes the IDE from the platform.
core.kit=NetBeans Platform
core.multiview=MultiView Windows framework and APIs
core.nativeaccess=Uses native bindings via JNA library to provide advanced visual effects for window system.
core.output2=A simple text area based output window implementation
core.startup=Loads and enables modules.
core.ui=User interface of the platform.
core.windows=Implementation for windowing support.
css.editor=Editor support for editing CSS files
css.visual=CSS authoring support module for visual CSS editing
dbapi=Database support APIs
db.core=Core database support.
db.dataview=SQL query editable resultset view
db.drivers=JDBC database drivers
db.kit=Database browser, visual and text SQL editor.
db.mysql.sakila=Provides Sakila sample database for NetBeans MySQL support
db.mysql=Provides MySQL-specific db support for NetBeans
dbschema=Enables you to capture and view the structure of a database in the IDE.
db.sql.editor=Supports editing SQL files in the IDE
db.sql.visualeditor=Visual Query Editor
db=Views and modifies the structure of the connected database.
debugger.jpda.ant=Lets you use the NetBeans JPDA debugger from Ant.
debugger.jpda.heapwalk=Provides heap walking functionality in Java Debugger.
debugger.jpda.projects=JPDA Debugger integration with Java projects.
debugger.jpda=Enables debugging with the JPDA debugger implementation.
debugger.jpda.ui=JPDA Debugger.
defaults=Contains font, color and shortcut defaults for IDE.
deployment.wm=Windows Mobile Deployment
derby=Integration with the Java DB database.
diff=Provides the diff action to view file differences.
editor.bookmarks=Contains support for bookmarks handling in the edited files
editor.bracesmatching=Support for highlighting matching braces
editor.codetemplates=Contains support for creation and using of code templates
editor.completion=Contains support for Code Completion in Editor
editor.errorstripe.api=The API for the right hand side bar showing errors, hints, etc.
editor.errorstripe=The right hand side bar showing errors, hints, etc.
editor.fold=Contains support for Code Folding in Editor
editor.guards=Provides support for manipulating garded sections in a document.
editor.indent=Contains indentation APIs and SPIs.
editor.kit=Editting support for various types of files.
editor.lib2=Contains core editor APIs and SPIs.
editor.lib=Contains Editor functionality independent on the IDE
editor.macros=Support for editor macros
editor.mimelookup.impl=The default implementation of MimeDataProvider.
editor.mimelookup=The MIME lookup API.
editor.plain.lib=Contains plain editor library implementation
editor.plain=Contains plain text editor implementation
editor.settings=Contains support for editor settings
editor.settings.storage=Implements Netbeans editor settings storage
editor=Enables editing of files in the IDE.
editor.structure=Contains Editor support functionality for tag based editors
editor.util=Contains various support classes for editor related modules
el.lexer=Lexical Analysis for Expression Language
etl.editor=Data Editor for editing and creating extract-transform-load collaboration documents.
etl.project=Data Integrator Application Projects.
extbrowser=Enables integration of external web browsers with the IDE.
extbrowser=Webclient module enables embedding of external web browsers into the IDE.
extexecution=Supports execution of external processes
favorites=Support for organizing favorite files.
form.kit=Enables you to visually design Java desktop (AWT and Swing) applications.
glassfish.common=Shared support module for GlassFish V3 server integration
glassfish.eecommon=shared code for glassfish servers
glassfish.javaee=GlassFish V3 server support for JavaEE projects.
glassfish.jruby=GlassFish V3 server support for Ruby on Rails projects
gototest=An action to quicky \
groovy.editor=Support for editing Groovy files
groovy.grailsproject=Support for Grails projects
groovy.grails=Interface to in-process or ex-process Grails runtime
groovy.gsp=Support for Groovy Server Pages (GSP)
groovy.kit=Wrapper module for all Groovy and Grails functionality
groovy.refactoring=Groovy refactorings
groovy.samples=Groovy and Grails sample projects
groovy.support=Enables editing and running of scripts written in Groovy language.
groovy.support=Groovy script execution support
gsf.api=API for defining custom languages in the IDE
gsfpath.api=APIs for handling paths in the Common Scripting Language Framework
gsf=Generic support for language integration in the IDE
gsf=Adds support for structural views of Java \
gsf=Java Source Infrastructure
hibernatelib=Wrapper module for Hibernate 3.2.5 jars
hibernate=Hibernate Support
hibernateweb=Hibernate Support for Web Projects.
html.editor.lib=Contains HTML editor library implementation
html.editor=Contains HTML editor implementation
html.lexer=Lexical analysis for html language
html=Supports creation, editing, and viewing of HTML files.
httpserver=Provides infrastructure for testing applets, RMI applications, and so on.
i18n.form=Enables internationalization of files created with the IDE's Form Editor.
i18n=Simplifies internationalization of applications.
ide.branding.kit=NetBeans IDE content and branding.
ide.branding=Provides NetBeans IDE specific branding
ide.kit=IDE Platform
identity.kit=Plugin for securing web services and clients using Sun Java System Access Manager.
identity.samples=Identity Sample Projects
iep.editor=Intelligent Event Processor Editor
iep.help=Intelligent Event Processor Help Topics.
iep.project=Intelligent Event Processing Module Project
iep.samples=Intelligent Event Processing Samples.
image=Supports viewing of image files.
installer=Provides integration services between the NetBeans installer and the Plugin Manager
j2ee.ant=Lets you use j2eeserver from Ant.
j2ee.api.ejbmodule=APIs for ejb jar development support modules.
j2eeapis=J2EE Application Deployment and Management API Library
j2ee.archive=Java EE Binary Archives support
j2ee.clientproject=Support for Application Client (CAR) Module Projects.
j2ee.common=Utilities for J2EE projects
j2ee.core.utilities=Core Java EE Utilities.
j2ee.ddloaders=J2EE Deployment Descriptors files loaders
j2ee.dd=Deployment Descriptor API.
j2ee.dd=J2EE Deployment Descriptor API.
j2ee.dd.webservice=Web Services Deployment Descriptor API.
j2ee.earproject=Supports development of composite Java EE applications.
j2ee.ejbcore=Support for Enterprise JavaBeans (EJB) Development.
j2ee.ejbjarproject=Support for Enterprise JavaBeans (EJB) Module Projects.
j2ee.ejbverification=EJB Verification
j2ee.genericserver=Generic J2EE Server Plugin
j2ee.jboss4=Plugin for JBoss Application Server
j2ee.jpa.verification=Detects and solves problems with usage of the Java Persistence API
j2ee.kit=J2EE / Java EE application support
j2ee.metadata=Java EE Metadata
j2ee.persistenceapi=API for supporting Java Persistence API
j2ee.persistence.kit=Java Persistence API support
j2ee.persistence=Support for the Java Persistence Technology
j2ee.platform=Java EE Documentation
j2ee.samples=Java Enterprise Samples from the GlassFish samples project
j2eeserver=Supports Java EE application servers
j2eeserver=JSR88/77 test server plugin
j2ee.sun.appsrv81=Map Java classes to database schema
j2ee.sun.appsrv81=GlassFish and Sun Java System Application Server integration
j2ee.sun.appsrv=Sun Java System Application Server  Common APIs
j2ee.sun.dd=Sun Java Sytem Application Server J2EE Deployment Descriptor API.
j2ee.sun.ddui=Sun Java Sytem Application Server (or Glassfish) JavaEE Deployment Descriptor Loaders.
j2ee.sun.ddui=Sun Java Sytem Application Server J2EE Deployment Descriptor GUI.
j2ee.toplinklib=Java Persistence API and TopLink Essentials Library
j2ee.weblogic9=Plugin for BEA WebLogic Server
j2ee.websphere6=Plugin for IBM WebSphere Application Server, Version 6.0 and 6.1
j2me.cdc.kit=Support for Connected Device Configuration development (JSR 36 and JSR 218)
j2me.cdc.platform.bdj=Java ME CDC BD-JRay Platform Support
j2me.cdc.platform.nsicom=Java ME CDC NSIcom VM Platform Implementation
j2me.cdc.platform=Java ME CDC Platform
j2me.cdc.project.bdj=Java ME CDC BD-J Plugin Implementation
j2me.cdc.project.execuiimpl=Implementation of executable classes chooser in CDC profiles
j2me.cdc.project.execui=Internal API for executable classes chooser in CDC profiles
j2me.cdc.project.nsicom=Java ME CDC NSIcom Plugin Implementation
j2me.cdc.project=Supports Java ME CDC Projects, such as for mobile client-side Java.
java.api.common=API implementations common to all the project types.
java.debug=Navigator for Java AST
javadoc=Supports Javadoc creation and searches.
java.editor.lib=Contains java editor library implementation
java.editor=Contains java editor implementation
java.examples=Provides Java SE application samples.
java.freeform=Support of Java development in Freeform project.
java.guards=Provides Java Guarded Sections implementation
java.helpset=Java Support Documentation
javahelp=Permits JavaHelp help sets to be added to the IDE.
java.hints.analyzer=Javadoc Analyzer
java.hints.analyzer=Task List window implementation
java.hints=Hints Provider for Java
java.j2seplatform=General-purpose Java platform and library definitions.
java.j2seproject=Supports plain Java projects, such as for client-side Java SE.
java.kit=Support for development in Java.
java.lexer=Lexical analysis for java language
java.navigation=Adds support for structural views of Java \
java.platform=Infrastructure and APIs for configuring and searching Java platforms.
java.project=Support for defining Ant-based project types involving Java sources.
javascript.hints=Additional source code hints for JavaScript
javascript.kit=An umbrella module covering all modules required for JavaScript support: editing, refactoring, hints, etc.
javascript.libraries.dojo=Installs the Dojo JavaScript Library
javascript.libraries.jquery=Installs the jQuery JavaScript Library
javascript.libraries.prototype=Installs the Prototype JavaScript Library
javascript.libraries.scriptaculous=Installs the Scriptaculous JavaScript Library
javascript.libraries=JavaScript Library Manager
javascript.libraries.yahooui=Installs the YahooUI JavaScript Library
java.source=Java Source Infrastructure
java.sourceui=UI classes for Java source files
javawebstart=Support for Java Web Start
jconsole=JConsole module
jellytools=A library used for GUI-testing NetBeans IDE.
jemmy=Jemmy test library.
jmx.common=Common classes for JMX and JConsole NetBeans modules
jmx=JMX Wizard module
jsp.lexer=Lexical analysis for JSP language
jumpto=An action to quicky \
jumpto=Open Type allows you to jump to type declarations in other files
junit=Creates tests suitable for the JUnit framework.
languages.bat=Support for .bat files editing.
languages.css=Support for editing CSS files.
languages.diff=Support for editing .diff files.
languages.javascript=Support for editing JavaScript files.
languages.manifest=Support for editing .manifest files.
languages.php=PHP editor.
languages.refactoring=Refactorings for Generic Support for Integration of Programming Languages into NetBeans IDE
languages.sh=Support for editing .sh files.
languages=Generic Support for Integration of Programming Languages into NetBeans IDE
languages.yaml=Support for editing YAML files.
lexer.editorbridge=Enables use of the lexer module with the current editor
lexer.nbbridge=Allows to search for language descriptions by using MimeLookup
lexer=Enables lexical analysis
lib.cvsclient=A CVS client library, that substitutes the client side of the native CVS executable.
libs.aguiswinglayout=Free Layout for AGUI Profile based on org.jdesktop.layout.GroupLayout
libs.bytelist=JRuby ByteList Library
libs.cglib=This module bundles Code Generation Library
libs.commons_fileupload=This plugin bundles Commons FileUpload.
libs.commons_logging=This module bundles Apache Commons Logging.
libs.commons_net=This plugin bundles Commons Net.
libs.freemarker=This module bundles Freemarker.
libs.glassfish_logging=This module bundles Glassfish Commons Logging.
libs.httpunit=HttpUnit Test.
libs.ini4j=Bundles ini4j.jar.
libs.jakarta_oro=This plugin bundles Jakarta ORO.
libs.javacapi=The javac public API
libs.javacimpl=The javac implementation classes.
libs.javacup=Java CUP 11a integration
libs.jna=Bundles JNA library.
libs.jsch=Bundles JSch (SSH implementation).
libs.jsr223=This module bundles the Scripting APIs
libs.junit4=Bundles the JUnit 4.x testing library.
libs.jvyamlb=YALM Library Library (jvyamlb)
libs.lucene=Bundles Apache Lucene (a Search Engine).
libs.ppawtlayout=Free Layout for Personal Profile based on org.jdesktop.layout.GroupLayout
libs.springframework=Bundles the Spring Framework.
libs.svnClientAdapter=Bundles tigris.org's svnClientAdapter.jar.
libs.svnjavahlwin32=Bundles subversion client for windows
libs.xerces=Bundles Apache Xerces (an XML parser).
libs.xmlbeans=XMLBeans development and runtime libraries
lib.terminalemulator=A terminal emulator library written in Java.
lib.uihandler=Collects Information about UI Gestures
loadgenerator=Generic load generation infrastructure
localhistory=Implemets Local History for the IDE
masterfs=Merges multiple filesystem providers into a single logical tree.
maven.kit=NetBeans Maven project system support
maven.spring=Module bridging Maven and Spring features
mercurial=Mercurial Versioning System
mobility.antext=Provides Java ME extensions to Ant.
mobility.cldcplatform.catalog=Java ME Platform SDK Catalog
mobility.cldcplatform=Java Micro Edition CLDC Platform
mobility.databindingme=Provides runtime libraries for databinding on mobile devices.
mobility.deployment.ftpscp=FTP/SCP Deployment of Java ME Project
mobility.deployment.nokia=Deployment on Nokia phones
mobility.deployment.ricoh=Deployment on Ricoh devices
mobility.deployment.sonyericsson=Sony Ericsson Deployment of Java ME Project
mobility.deployment.webdav=WebDAV Deployment of Java ME Project
mobility.editor=Java Micro Edition Editor Support module
mobility.end2end.kit=Support for mobile end-to-end applications such as Java ME web services or mobile to web
mobility.end2end=Java ME Client to Web Application Generator
mobility.javahelp=Online documentation for Java ME.
mobility.jsr172=Stub generator for Java ME Web Service Clients (JSR 172)
mobility.kit=Java Mobile Edition System Core
mobility.licensing=Mobility Licensing module.
mobility.midpexamples=Provides a lot of MIDP examples.
mobility.plugins.mpowerplayer=SDK MPowerPlayer support for Netbeans Mobility
mobility.proguard=Provides ProGuard Obfuscator for Java ME extensions to Ant.
mobility.project.ant=Debugger support for Java ME Build System Core
mobility.project.bridge.impl=Implementation of isolation API between core Mobility project and advanced IDE functionality
mobility.project.bridge=Isolation API between core Mobility project and advanced IDE functionality
mobility.project=Java Mobile Edition Build System Core
mvd=Java Mobile Edition Visual Editor
nbjunit=NetBeans extensions to JUnit
o.apache.jmeter.kit=JMeter load generator integration bundle
o.apache.jmeter.module=JMeter integration module
o.apache.tools.ant.module.docs=Documentation for the Ant build tool.
o.apache.tools.ant.module=Supports writing of build scripts.
o.apache.xml.resolver=Apache Resolver library for development time
o.jdesktop.beansbinding=Bundles beans-binding library.
o.jdesktop.layout=Bundles swing-layout library.
o.jruby.distro=Bundled distribution of JRuby and Ruby on Rails
o.jruby=The actual JRuby implementation
o.kxml2=XML Pull Parser implementation
o.mozilla.rhino.patched=A patched version of Rhino for IDE language processing
o.n.bluej=Allows to work with BlueJ projects in NetBeans
o.n.bootstrap=The core bootstrap of NetBeans-based applications.
o.n.core=The basic framework of NetBeans-based applications.
o.n.insane=INSANE heap profiling library.
o.n.soa.libs.jgo=Wrapper module for the JGO visual library.
o.n.soa.libs.wsdl4j=WSDL4J
o.n.soa.libs.xmlbeans=XMLBeans development and runtime libraries
o.n.swing.dirchooser=\
o.n.swing.plaf=Handles per-look-and-feel UIManager customizations for NetBeans
o.n.swing.tabcontrol=The tab control used by the window system
o.n.upgrader=Import IDE environment and settings.
o.n.xml.libs.jxpath=JXPath Library.
o.openidex.util=Search API for use by various modules.
openide.actions=Definition of common actions for NetBeans
openide.awt=User interface utilities.
openide.compat=Some old classes that are now deprecated.
openide.dialogs=Handles dialogs and wizards.
openide.execution=Execution API from the Open APIs.
openide.explorer=Various view for displaying node structures.
openide.filesystems=Virtual File System API.
openide.io=Open APIs relating to displaying output.
openide.loaders=NetBeans Open API for manipulating data objects.
openide.modules=APIs for getting information about installed modules.
openide.nodes=API for defining generic tree-like structures.
openide.options=Support for storing preferences.
openide.text=Generic API wrapping Swing based EditorKits.
openide.util.enumerations=Enumeration API that is in wrong package.
openide.util=Basic Utilities API.
openide.windows=API for managing components on a screen.
options.api=Provides the Options dialog and an SPI to add panels to it.
options.editor=Provides the editor related panels in the Options dialog.
o.rubyforge.debugcommons=Integration of debug-commons-java library
performance=The basic core framework of the IDE.
performance=The basic core framework of the IDE.
php.dbgp=PHP Debugger.
php.doc=PHP Documentation.
php.editor=Support for editing PHP files
php.help=Online help pages for the IDE's PHP support
php.kit=Provides tools and support for php development.
php.lexer=PHP Lexer
php.model=PHP model.
php.project=Support for PHP projects.
php.rt=PHP runtime explorer.
php.samples=PHP Sample projects for NetBeans Sample Catalog
print=Implementation of print module.
profiler.attach=Attach wizard integration provider SPI
profiler.loadgen=Profiler -> LoadGenerator Bridge
progress.ui=Task progress visualization.
project.ant=Supports all project types based on Ant as a build tool.
projectapi=General API for accessing and loading IDE projects.
projectimport.eclipse.core=Imports projects created in Eclipse IDEs into NetBeans.
projectimport.jbuilder=Imports projects created by JBuilder IDE into NetBeans.
project.libraries=Support for organizing resources into libraries.
projectuiapi=Supplies the APIs/SPIs for user interface of projects in the IDE.
projectui.buildmenu=Supplies the Run and Debug menu for java/c++ projects.
projectui=Supplies the basic user interface for projects in the IDE.
properties=Supports editing of .properties files.
properties.syntax=Syntax coloring for .properties files in the source editor.
queries=Acts as a general communication channel between modules.
quiz=Quiz Module
registration=Enables user to register to Sun Online Account
ruby.debugger=Ruby Debugger
ruby.extrahints=Extra source code hints for Ruby
ruby.help=Online help pages for the IDE's Ruby support
ruby.hints=Additional source code hints for Ruby
ruby.javaint=Support for accessing Java libraries using JRuby in Ruby projects
ruby.kit=An umbrella module covering all modules required for Ruby support: editing, projects, Rails, etc.
ruby.platform=Infrastructure and APIs for configuring and searching Ruby platforms.
ruby.project=Supports plain Ruby projects
ruby.rakeproject=Supports all project types based on Rake as a build tool.
ruby.rspec=Support for RSpec, a testing framework for Ruby
ruby.samples.depot=Depot Sample Application
ruby.testrunner=Ruby Test Runner
ruby.themes=Additional editor color themes designed for use with the Ruby file types in NetBeans.
schema2beans=Library for representing XML as java beans; development time variant.
schema2beans=Library for representing XML as JavaBeans.
sendopts=GetOpts compliant API for parsing command line
server=Provides server integration.
servletapi=Servlet 2.2 API Library
servletjspapi=Servlet 2.5/JSP 2.1 API Library
settings=A library for storing settings in custom formats.
soa.kit=Shared classes for XSLT and BPEL modules.
soa.mappercore=SOA Mapper Core.
soa.mapper=SOA Mapper.
soa.reportgenerator=SOA Report Generator Framework.
soa.ui=SOA UI.
soa.validation=SOA Validation.
spi.debugger.ui=Basic shared debugger UI.
spi.editor.hints=Editor Hints Infrastructure
spi.navigator=Navigation support SPIs and APIs
spi.palette=Common Palette visualization and APIs
spi.quicksearch=Infrastructure for quick search in menu items, actions, files etc.
spi.tasklist=Provides API for Task List plugins
spi.viewmodel=TreeTableView Model
spring.beans=Spring Beans Support
spring.webmvc=Spring Web MVC Support
sql.help=JDBC Help.
sql.project=Composite Application Base Project.
sql.project=Support for SQL Application Projects.
sql.wizard=JDBC Wizard.
subversion=Integrates Subversion actions into IDE workflow.
swingapp=Swing Application Framework Support for Form Editor
tasklist.projectint=Integrates the Task List window with Projects system
tasklist.todo=Scan for ToDo items in source file comments
tasklist.ui=Task List window implementation
templates=Advanced Templating not only for Datasystems
testtools: Module providing additional support for XTest, Jemmy and Jelly technologies.
timers=Timers API
tomcat5=Tomcat servlet container integration
uihandler.exceptionreporter=Allows automatic reporting of exceptions to our UI Gestures Server
uihandler.interactive=Collects Information about UI Gestures
uihandler=Collects Information about UI Gestures
uml.codegen=Code Generation for the UML Tools
uml.designpattern=The Design Center provides the design pattern catalog.
uml.documentation=Provides a control to view and modify the documentation of a model element.
uml.dom4jlib=Dom4j Dependency Libraries
uml.drawingarea=The modeling drawing area control.
uml.drawingarea=Reverse Engineer GUI Addin.
uml.integration=Enables model-driven analysis, design and implementation using the Unified Modeling Language (UML).
uml.kit=NetBeans 5.5, UML Modeling Module
uml.parser.java=Provides parsing support for the Java 5.0 language.
uml.project=Supports plain UML projects
uml.propertysupport=Supports UML properties
uml.reporting=Provides the ability to execute web report.
uml.requirements.doorsprovider=A requirements provider that uses DOORS to persist requirements.
uml.requirements=The requirements framework.
uml.requirements.xmlrequirements=A requirements provider that uses an XML file to persist requirements.
uml.samples=A sample Java project with its reversed engineered UML project counterpart.
uml.samples=Sample UML Model Projects
uml=Contains the core functionality for all modeling projects.
uml=Associate With Dialog Addin.
updatecenters=Declares NetBeans autoupdate centers.
usersguide=Online documentation for the IDE.
utilities.project=Support for searching projects for files.
utilities=Support for file searching, bookmarks.
versioning=Support module for Versioning systems.
versioning.system.cvss=Integrates CVS actions into IDE workflow.
visdev.prefuse=Library for Prefuse Graphing Toolkit
visualweb.api.designer=Visual Editor Hack APIs
visualweb.api.insync=InSync Source Modeler APIs
visualweb.api.j2ee=API Extensions for J2EE
visualweb.api.portlet.dd=Provides an API for a portlet deployment descriptor
visualweb.compatibilitykit=Contains libraries needed for Visual Web JSF web application development in certain environments
visualweb.dataconnectivity.designtime=Design Time Classes for Data Connectivity
visualweb.dataconnectivity=Database and Data Source related
visualweb.designer.markup=Designer Markup and CSS Impl.
visualweb.designer=The Visual Designer enables you to create pages in WYSIWYG mode
visualweb.designtime.base=Base design-time implementations
visualweb.designtimeext=Design-Time API Extension for component authors
visualweb.designtime=Design-Time API
visualweb.designtime=Design-Time API for component authors
visualweb.ejb=Enterprise Java Bean Support
visualweb.errorhandler.client=Web Application error handler client
visualweb.errorhandler=Web Application error handler server
visualweb.extension.openide=Extends Openide.
visualweb.gravy=A library used for GUI-testing NetBeans IDE Visual Web features.
visualweb.insync=InSync provides abstract source manipulation support for Java, XML, and HTML
visualweb.jsfsupport.components=JSF Components
visualweb.jsfsupport.designtime=Visual Web Design-Time support and standard JSF components
visualweb.jsfsupport=JSF Support Container
visualweb.kit=Visual development of web applications with Java Server Pages
visualweb.libs.batik=Batik CSS Parser (modified)
visualweb.libs.jtidy=JTidy HTML cleaner (modified)
visualweb.libs.rowset=JDBC RI Rowset Library
visualweb.project.jsfloader=JSF Loaders faking one JSF object.
visualweb.project.jsf=Support for development of web applications based on JavaServer Faces.
visualweb.project.jsf=Supplies the basic user interface for projects in the IDE.
visualweb.propertyeditors=Property Editors
visualweb.ravehelp.rave_nbpack=Online help pages for the IDE
visualweb.websvcmgr=Web Service Support
visualweb.web.ui.appbase=Application Runtime API
visualweb.webui=Wrapper module for Sun Web User Interface Component runtime library
visualweb.webui.themes=Default themes for the Sun Web UI Components
visualweb.xhtml=Defines beans for most XHTML elements
vmd.analyzer=Visual Mobile Designer - Analyzer
vmd.codegen=Visual Mobile Designer - Code Generator
vmd.components.midp.pda=JSR 75: Accessing the PIM database and File system custom components.
vmd.components.midp=Provides basic set of Netbeans MIDP custom components.
vmd.components.midp.wma=Wireless Messaging API (WMA) custom components.
vmd.componentssupport=Visual Mobile Designer - components creation
vmd.componentssupport=VMD Custom Component Project
vmd.componentssupport=VMD Custom Component Project
vmd.componentssupport=VMD Custom Component Project
vmd.flow=Visual Mobile Designer - Flow Designer
vmd.game=Visual editing support for MIDP 2.0 Game API
vmd.inspector=Visual Mobile Designer - Inspector
vmd.io.javame=Visual Mobile Designer - Java ME Communication IO Implementation
vmd.io=Visual Mobile Designer - Input Output
vmd.kit=Support for visual development in JavaME.
vmd.midpnb=Visual Mobile Designer - MIDP NetBeans Components
vmd.midp=Visual Mobile Designer - MIDP
vmd.model=Visual Mobile Designer - Model
vmd.palette=Visual Mobile Designer - Palette
vmd.properties=VMD Properties
vmd.screen=Visual Mobile Designer - Screen Designer
vmd.structure=VMD Structure Browser
web.client.javascript.debugger.ant=Lets you use the NetBeans JavaScript debugger from Ant.
web.client.tools.firefox.extension=This module implements the JavaScript Debugger Firefox Extension.
web.client.tools.impl=This module contains the Web Client JavaScript Debugger API classes.
web.client.tools.impl=This module contains the Web Client JavaScript Debugger UI classes.
web.client.tools.impl=Web Client Tools Implementation.
web.client.tools.internetexplorer=This module implements the NetBeans Add-on for Internet Explorer.
web.client.tools.kit=Support for web client tools.
web.core=Supports the creation, editing, compiling, and testing of JavaServer Pages.
web.core.syntax=Provides editing support for JSP files.
web.debug=Supports the debugging of JSP
web.examples=Provides web application examples.
web.flyingsaucer=Allows to render XHTML documents using CSS
web.freeform=Support of Web development in Freeform project.
web.jsf12ri=Wrapper module for JavaServer Faces 1.2 RI
web.jsf12=Installs the JavaServer Faces 1.2 Library
web.jsf.kit=JavaServer Faces support.
web.jsf.navigation=The Page Flow Editor lets you edit page flow
web.jsf=Support for development of web applications based on JavaServer Faces.
web.jspparser=Provides support for parsing JSP files using the Jakarta JSP parser.
web.jstl11=Installs the JSP Standard Tag Library 1.1.
web.kit=Basic Java web application support.
web.libraries.jsf1102=Installs the JavaServer Faces 1.1.02 Library
web.monitor=Tracks data flow inside the servlet engine
web.project=Support for web module projects.
web.struts=Support for Struts Framework
websvc.axis2=Axis2 Support
websvc.clientapi=SPI for modules that are web service consumers.
websvc.core=Provides generic support for development and consumption of web services.
websvc.customization=Provides support for JAX-WS customization.
websvc.design=Visual Designer for Web Services
websvc.editor.hints=Hints support for JAXWS Web Services
websvc.jaxrpc16=Installs the JAX-RPC libraries from JWSDP 1.6
websvc.jaxrpckit=JAX-RPC Web Services Development Support
websvc.jaxrpc=Provides support for development and consumption of JAX-RPC web services.
websvc.jaxws21api=JAX-WS 2.1 API
websvc.jaxws21=Installs the JAX-WS 2.1 client libraries
websvc.jaxwsapi=SPI for modules that are JAX-WS service providers.
websvc.jaxwsmodel=JAX-WS(wsimport) WSDL to Java model and project support for JAX-WS technology.
websvc.kit=Provides generic support for development and consumption of web services.
websvc.manager=IDE-wide registration for web services
websvc.metro.samples=Provides examples of Metro web services
websvc.projectapi=Web Services Project API
websvc.registry=Web Services Implementation
websvc.registry=Web Service Registry Implementation
websvc.restapi=API/SPI for RESTful Web Services Support
websvc.restkit=RESTful Web Services Development Support
websvc.restlib=Installs JAR files for JSR-311 API and reference implementation.
websvc.rest.samples=RESTful Web Services Sample Projects
websvc.rest=Support for creation of RESTful Web Services
websvc.saas.api=API supporting consumers of SaaS (Software as a Services)
websvc.saas.codegen.j2ee=Provides code generation support for consuming SaaS services in Java EE applications.
websvc.saas.codegen.java=Provides code generation support for consuming SaaS services in Java desktop applications.
websvc.saas.codegen.php=Provides code generation support for consuming SaaS services in PHP applications.
websvc.saas.kit=Provides support for consuming SaaS services.
websvc.saas.services.strikeiron=StrikeIron Service Component
websvc.saas.services.strikeiron=StrikeIron Service Component
websvc.saas.ui=SaaS Services UI
websvc.utilities=Utilities for Web Services
websvc.websvcapi=SPI for modules that are JAX-RPC service providers.
websvc.wsitconf=Provides support for web services interoperability technologies.
websvc.wsitmodelext=Provides WSDL extensions to other (WSIT or other) modules.
websvc.wsstackapi=Web Services Stack API
websvc.wsstack.jaxws=JAX WS Stack Description
welcome=Shows welcome content after the first startup of the IDE.
wsdlextensions.file=FILE extension for wsdl editor.
wsdlextensions.ftp=FTP extensions in WSDL editor.
wsdlextensions.jms=Provides JMS extensions in WSDL editor.
wsdlextensions.snmp=Provides SNMP extensions in WSDL editor.
xml.catalog=The module allows to persistently mount entity catalogs.
xml.core=This module keeps some miscellaneous APIs.
xml.jaxb=Java XML binding wizard and utilities.
xml.kit=XML, Schema and WSDL related tools.
xml.multiview=XML Multiview Editor Infrastructure
xml.nbprefuse=Prefuse Customization Module
xml.refactoring=Refactoring support for XML-based components.
xml.refactoring=Graph Analysis of XML Schema Relationships
xml.retriever=Retriever and XML catalog support
xml.schema.abe=Support for the graphical design view of the schema editor
xml.schema.model=API for manipulating XML Schema
xml.schema.refactoring=Refactoring of Schema Component Usages
xml.schema=The module provides support for XML Schema.
xml.search=XML Search.
xml=The module is a base for all XML related modules.
xml.tax=The module contains Tree API for XML ("TAX") library.
xml.text=The module provides text editing capabilities.
xml.tools.java=The module contains various actions and generators.
xml.tools=The module contains various actions and tools.
xml.validation=XML Validation module
xml.wsdl.bindingsupport.api=WSDL Binding Support API
xml.wsdl.bindingsupport=WSDL Extensibility Elements Support
xml.wsdl.extensions=Extensions to WSDL Model
xml.wsdlextui=WSDL Editor Extensions.
xml.wsdl.kit=WSDL related tools.
xml.wsdl.model=WSDL Model
xml.wsdl.refactoring=Support for XML Refactoring in WSDL
xml.wsdlui=WSDL Editor for editing and creating WSDL documents.
xml.wsdlui=FTP extensions in WSDL editor.
xml.wsdlui=Provides JMS extensions in WSDL editor.
xml.xam=Framework for design synchronous object model from textual document.
xml.xam.ui=Interface code common to clients of the XAM model.
xml.xdm=An toolable document model for XML
xml.xpath.ext=XPath model with deep resolving of schema objects
xml.xpath=XPath 1.1 Model.
xsl=The module contains simple XSL support.
xslt.core=XSLT Core.
xslt.help=XSLT Help.
xslt.kit=XSLT development support.
xslt.mapper=XSLT Mapper.
xslt.model=XSLT Model.
xslt.project=XSLT Project.
xslt.tmap=Transformmap Core.
xslt.validation=XSLT Validation.

When you're creating an application on the NetBeans Platform in NetBeans IDE, you can right-click the app in the Projects window, choose Properties, and then go to the Libraries tab. There you'll see a list of clusters containing the modules you can add to your application.

What are they all for? Here's the answer.

platform cluster

nb cluster

ide cluster

java cluster

harness cluster

apisupport

websvccommon

profiler

If you think you have found a bug in the NetBeans Platform or IDE which affects your module development, please file it so it can be fixed. Generally exceptions coming from platform code are bugs in NetBeans (unless it is e.g. an IllegalArgumentException thrown after your code called a method with invalid arguments). Other things can of course be bugs if NetBeans is not behaving according to its documentation, or if something just looks wrong.

1. Reread all relevant documentation to see if you have missed anything important.
2. If you are unsure whether the behavior is really incorrect, you can ask on dev@platform.netbeans.org. Do not be too shy to file a bug, though; it is just as easy to close an invalid bug report as it is to reply to the mailing list.
3. If at all possible, figure out how to reproduce your bug. From scratch: the assignee of the bug report cannot see your computer and has no idea what you are working on or why. Try to make a minimal, self-contained test case that anyone could run to see the bug in action. Often a suite project is a good test case - attach a ZIP of sources, including nested module projects. If you know how to write a unit test for the buggy module, that is ideal, but this can require some deeper knowledge of NetBeans internals. Sometimes a bug occurs that just cannot be easily reproduced - it is still fine to file a bug, but include as much diagnostic information as you can and do not be surprised if it does not get fixed.
4. Read: Issue Reporting Guidelines
5. For general background you may also want to read: How To Ask Questions The Smart Way
6. File a bug report and include at least
   1. Some background on what you are trying to accomplish and why.
   2. Some kind of test case to demonstrate the bug.
   3. Instructions for running the test case.
   4. What you would expect to see happen.
   5. What you actually see happen.
7. Be patient as the bug is assigned and evaluated, and provide additional information if requested. If all goes well it should be fixed for a future NetBeans release. The evaluator may also be able to offer some workarounds for use in current releases.

There are a large number of samples. Many of these correspond to the tutorials. You can find the samples in module platform in main/misc repository at hg.netbeans.org. They are in the samples/ subdirectory.

The platform/samples/ folder can be browsed online here. But for really trying things out it is usually more useful to have a local copy - then you can open them as projects in the IDE.

The NetBeans Javadoc has some additional documentation about using certain APIs. Unfortunately, the index page does not link to these and so they can be difficult to find. Here are direct links to these documents from the most recent builds:

• Actions API
• DataSystems API
• Explorer API
• FileSystem API
• Module System API
• Nodes API
• Utilities API
• Window System API

This is a wiki page for NetBeans Certified Engineer Course, read more at our main website.

Exercises/Assignments

• NetBeansCertifiedEngineerExercises
• Link to Tutorials You Can Write
• Link to Hints You Can Provide

Papers

• Rich Client Programming
• NetBeans Platform

Slides from the Training on the First Day

• Presentation 1: NetBeans Platform (PDF Version)
• Presentation 2: A First NetBeans Platform Application (PDF Version)
• Presentation 3: Dependency and Injection in Modular Systems (PDF Version)
• Presentation 4: An Introduction to the System FileSystem (PDF Version)
• Presentation 5: NetBeans JavaBeans (PDF Version)

Slides from the Training on the Second Day

• Presentation 1: NetBeans ~ OS/2 (PDF Version)
• Presentation 2: An Introduction to the Window System (PDF Version)
• Presentation 3: Contributing to Open Source Projects (PDF Version)
• Presentation 4: Ideas for Modules (PDF Version)

Setting $CLASSPATH or %CLASSPATH% on the command line will not affect anything - NetBeans uses its own class loader system to find classes from modules.

What you need is for your libraries to be a module; see DevFaqWrapperModules.

Applies to: NetBeans 6.8 and above

The nuts and bolts of module dependencies are as follows:

• Modules can load classes from modules they depend on. They have to declare a dependency on them.
• NetBeans does not care about things like the CLASSPATH environment variable - it knows how to find modules in an installation of NetBeans, and enforces dependencies between them.

What this means is that if

• Module B tries to use a class from module A, but module B does not explicitly state that it depends on A, or...
• Module B tries to use a class from module A, and it does declare a dependency on Module A, but the package that class is in is not in the list of packages A says other modules can touch...

then a NoClassDefFoundException will be thrown at runtime. (If you even get that far - the module build harness will refuse to even compile module B in such cases.)

An exception to the second item is that if Module B declares an implementation dependency on module A, then it will have access to the full set of classes. Normally you should not need to do this, and anyway it will then be hard to upgrade B independently of A.

Modules can also load classes from libraries - JAR files that are packaged with the module (see DevFaqHowPackageLibraries). Some points to remember about libraries:

• They are delivered to the user inside the NBM file if they are not part of a full application based on NetBeans.
• When unpacked, the module will end up in $SOMECLUSTER/modules/ and any libraries will end up in $SOMECLUSTER/modules/ext/.
• The module will use the library by having an entry in its manifest Class-Path: ext/someLibrary.jar the same way any JAR would.

If you are using the IDE's module development support, you will manage module dependencies in the properties dialog for your module (or the Libraries node in the Projects tab). This just modifies yourmodule/nbproject/project.xml. The data saved there is then used to generate the appropriate manifest entries for you.

If you are writing a module that will use some third party libraries, you probably want to read DevFaqWrapperModules and also DevFaqWhenUseWrapperModule.

For more details, see the reference documentation about classloading in NetBeans.

Applies to: NetBeans 6.8 and above

Adding an extra source directories is possible in case you need to create a separate output JARs (besides the module itself), generally with its own special classpath.

In your module's project.xml, add a declaration of the source root just before </data>:

<extra-compilation-unit>
    <package-root>othersrc</package-root>
    <classpath>...anything it might need to compile against...</classpath>
    <built-to>build/otherclasses</built-to>
    <built-to>${cluster}/modules/ext/other.jar</built-to>
</extra-compilation-unit>

This declaration has no effect on the build, but lets you work with the sources in the IDE's code editor.

You will separately need to add a target to your build.xml to compile and package these sources however you like. (You can name your target netbeans-extra and it will get run automatically toward the end of the module's build cycle.) If you define properties like a special classpath in project.properties, you can use the values in both build.xml and project.xml to minimize duplication.

You can also create a plain Java SE project in a subdirectory of your module and bundle its JAR. DevFaqWrapperModules describes a related technique.

Read the harness/README file under your Netbeans installation directory for information about issues like this one. The build harness has many capabilities not exposed through the GUI.

Applies to: NetBeans IDE 6.x Platforms: All

Overview

This FAQ item should be a companion to the main classpath documentation. Please refer to the original document for additional details.

Class loaders in the NetBeans platform

There are basically three main class loader types used in the platform. Most code is loaded by module class loaders. In special cases the "system" class loader can be used, when you need access to resources from unknown modules. Resources directly on the classpath from the launch script (mainly platform*/lib/*.jar) are loaded by the application loader. (There are also bootstrap and extension loaders in the JRE, and the platform has a special loader for a couple of JARs in platform*/core/*.jar.)

Most of the class loaders in the NetBeans platform are multi-parented class loaders. This means that the class loader can have zero or more parents. org.netbeans.ProxyClassLoader implements the search across multiple parents.

Module class loader

Every module loaded by the module system has its own class loader. This loader loads resources primarily from the module's JAR. The application loader is an implicit parent of each module loader.

The module loader is able to load from additional JARs (besides delegating to various parents):

• extensions - anything listed in the manifest attribute Class-Path of the module JAR
• locale extensions - JARs placed in a subdirectory locale relative to the original module JAR position, named by appending a locale suffix to the original name
• patches - JARs placed in a subdirectory patches/code-name-base relative to the original JAR position (can override module classes)

The implementation class is org.netbeans.StandardModule$OneModuleClassLoader.

System class loader

The "system" loader loads no resources on its own, but has as its parents all enabled module's class loaders. It is accessible via Lookup.getDefault().lookup(ClassLoader.class) or by using the fact that it is the context loader on all threads by default: Thread.currentThread().getContextClassLoader()

Application class loader

This class loader is set up by the launch script (or by javaws if running in JNLP mode). It can load classes from lib/*.jar in specified clusters. It is generally discouraged to use this loader for your own classes, but it is sometimes needed e.g. for Look & Feel classes (which must be loaded very early during the startup sequence).

Example

Take a very simple module a:

Manifest-Version: 1.0
OpenIDE-Module: org.netbeans.modules.a

and module b depending on a:

Manifest-Version: 1.0
OpenIDE-Module: org.netbeans.modules.b
OpenIDE-Module-Module-Dependencies: org.netbeans.modules.a
Class-Path: ext/library-b-1.1.jar

Classes in org-netbeans-modules-a.jar will be loaded in a's module class loader. Classes in both org-netbeans-modules-b.jar and library-b-1.1.jar will be loaded in b's module loader, and can refer to classes in org-netbeans-modules-a.jar.

Applies to: NetBeans 6.8 and above

You may encounter this problem while porting a Swing application to the NetBeans platform or when using a third-party library like SwingX. While the following code works in a standalone Swing application, it does not load the property in a platform-based application:

UIManager.getDefaults().addResourceBundle("com.example.foo.sample");
myLabel.setText(UIManager.getString("greeting"));

This fails in the platform because of JDK bug #4834404. Although the best solution is to replace the original code to load properties in a way that uses the correct class loader, that may not be possible when using a third-party library. In these cases, your module can work around the problem by using code similar to this:

UIDefaults def = UIManager.getDefaults();
ResourceBundle bundle = ResourceBundle.getBundle("com.example.foo.sample");
Enumeration<String> e = bundle.getKeys();
while (e.hasMoreElements()) {
   String key = e.nextElement();
   def.put(key, bundle.getString(key));
}

Yet another alternative is to ensure the resource bundles are available to the startup classloader. You can do this by placing the JAR containing the resource bundles in the lib subdirectory of your platform cluster, although this workaround has not been tested.

Note: An (untested) possible workaround is to first call UIManager.put ("ClassLoader", Lookup.getDefault().lookup(ClassLoader.class)).

Applies to: NetBeans 6.8 and above

Generally if it's a third party library (you didn't write it, you can't or don't want to change it), you will want to use a wrapper module (see DevFaqWrapperModules). An NBM file (a module packaged for delivery over the net) can contain more than one JAR, so all your libraries can be included in a single file that packages your module.

Note you can multi-select JARs in the New Library Wrapper Module wizard.

Since NetBeans 6.8 you can add, remove and assign sources and Javadoc to wrapped libraries in Project Properties dialog, Libraries / Wrapped JARs tab.

Advanced stuff

Before NB 6.8 you could add libraries manually to a standard module; or add additional libraries to an existing library wrapper module. The relevant data is in the project.xml for the module. What you would do is add entries similar to this one for each JAR.

<class-path-extension>
    <runtime-relative-path>ext/hexedit.jar</runtime-relative-path>          
    <binary-origin>release/modules/ext/hexedit.jar</binary-origin>
</class-path-extension>

Note if you want these libraries to be usable outside of the module they're declared in, then you must add the relevant packages to the list of public packages for that module.

Applies to: NetBeans 6.8 and later

See also

• Packaging A Distributable Java App
• German version

An NBM file is a NetBeans module packaged for delivery via the web. The principal differences between it and a module JAR are:

• It is compressed
• It can contain more than one JAR file - modules can package any libraries or other files they use into their NBM
• It contains metadata NetBeans will use to display information about it in the update center, such as the manifest contents, the license, etc.
• NBMs may be signed for security purposes

NBM files are just ZIP files with a special extension, which use the JDK's mechanism for signing JARs. Unless you're doing something unusual, you will not need to worry about the contents of NBMs - just let the standard Ant task for NBM creation take care of it for you. For those interested in gory details, read on.

Structure of an NBM

Below is an example of the contents of one - this is from the hexedit_integration module in contrib, which packages up an external library as well:

Info/info.xml

Metadata - this file is generated by the standard NBM build target, so if you use NetBeans support for creating modules, you should not need to do anything special to create it. This info is used by the IDE to figure out if a module the user is installing is newer or older, than an existing one, whether or not its dependencies can be satisfied, etc.

META-INF/MANIFEST.MF

The manifest - usually nothing of interest here, it is just generated because NBMs are created the same way that JARs are. May point to a signature for the NBM.

netbeans/....

Contents to be unpacked to some cluster in the NetBeans installation (or the user directory).

netbeans/config/Modules/org-netbeans-modules-hexeditor.xml

The module XML file used at runtime to discover modules. Indicates whether the module is autoload, etc.

netbeans/modules/org-netbeans-modules-hexeditor.jar

The actual module JAR.

netbeans/modules/ext/hexedit.jar

A library this module uses and includes.

Since NetBeans 6.9 NBM files now supports pack200 compression and all jar files in NBMs becomes compressed and have ".pack.gz" appended to the name e.g. modules/org-netbeans-modules-hexeditor.jar.pack.gz.

For more info about pack200 usage see DevFaqNBMPack200.

Runtime module XML metadata

The org-netbeans-modules-hexeditor.xml runtime metadata file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//NetBeans//DTD Module Status 1.0//EN"
                        "http://www.netbeans.org/dtds/module-status-1_0.dtd">
<module name="org.netbeans.modules.hexeditor">
    <param name="autoload">false</param>
    <param name="eager">false</param>
    <param name="enabled">true</param>
    <param name="jar">modules/org-netbeans-modules-hexeditor.jar</param>
    <param name="release">1</param>
 
    <param name="reloadable">false</param>
 
    <param name="specversion">1.0</param>
 
</module>

Module installation metadata - Info.xml

The Info/Info.xml file that NetBeans uses to figure out if it can install a module, dependencies, etc. looks like this (it also contains the license that the user will agree to to install the module from the update center):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//NetBeans//DTD Autoupdate Module Info 2.3//EN"
                        "http://www.netbeans.org/dtds/autoupdate-info-2_3.dtd">
<module codenamebase="org.netbeans.modules.hexeditor"
        homepage="http://contrib.netbeans.org/"
        distribution="http://...../org-netbeans-modules-hexeditor.nbm"
        license="standard-nbm-license.txt"
        downloadsize="0"
        needsrestart="false"
        moduleauthor=""
        releasedate="2005/08/29"
>
  <manifest OpenIDE-Module="org.netbeans.modules.hexeditor/1"
            OpenIDE-Module-Display-Category="Infrastructure"
            OpenIDE-Module-Implementation-Version="050829"
            OpenIDE-Module-Long-Description="Sample module hexeditor providing HexEdit"
            OpenIDE-Module-Module-Dependencies="org.openide.filesystems > 6.2, ..."
            OpenIDE-Module-Name="hexeditor"
            OpenIDE-Module-Requires="org.openide.modules.ModuleFormat1"
            OpenIDE-Module-Short-Description="Sample hexeditor module"
            OpenIDE-Module-Specification-Version="1.0"
  />
  <license name="standard-nbm-license.txt"><![CDATA[
                Sun Public License Notice
....
]]></license>
</module>

Applies to: NetBeans 6.5 and above

Yes, though there is not yet any GUI support for this.

1. Make a module project.

2. Generate a keystore, e.g.

cd .../path/to/module/
keytool -genkey -storepass specialsauce -alias myself -keystore nbproject/private/keystore

and answer the questions posed.

To make NetBeans build script sign the NBM module. The keystore and key password needs to be the same. At keytool, when the question below is asked, just press ENTER key, to make keystore and key alias the same password.

Enter key password for <myself>
  (RETURN if same as keystore password):

3. Edit nbproject/project.properties to contain e.g.

keystore=nbproject/private/keystore
nbm_alias=myself

4. Edit nbproject/private/platform-private.properties to contain e.g.

storepass=specialsauce

You could also pass -Dstorepass=specialsauce on the command line. If you specify a keystore but ${storepass} is undefined, you will be prompted for the password during the build.

5. Build the NBM for the module. (Context menu of the project.) It should be signed.

6. Try installing the NBM. (Expand build folder in Files view and double-click it.) It will not be trusted initially (and so the checkbox to really install it will initially be unchecked), since NetBeans does not know about your signature. But you can click View Certificate to examine the certificate. If you allow installation of this module, NetBeans will remember you approved this certificate and it will not ask you for confirmation next time.

Some notes:

1. You can probably get a root-authorized certificate from VeriSign or the like, and the Auto Update wizard should treat this as more trusted. Not yet investigated (please update this FAQ entry if you experiment with this).

2. Keeping the keystore and its password in the private dir ensures that you will not accidentally commit either to source repository or include it in a source ZIP made with the Project Packager module. It may be safe to put the keystore in a shared directory (e.g. nbproject) if you are sure that the storepass is too hard to guess.

Isn't there an easier way?

Of course. Based on the above notes this script has been contributed by our community. Just put this in your suite's build.xml file:

    <target name="-init" depends="suite.-init,init-netbeans,init-hudson">
        <!--Create/Update keystore-->
        <delete file="${keystore.location}${keystore.name}"/>
        <mkdir dir="${keystore.location}"/>
        <genkey alias="${keystore.alias}" storepass="${keystore.password}"
        dname="${keystore.dname}"
        keystore="${keystore.location}${keystore.name}"/>
        <!--Update keystore info in projects-->
        <antcall target="update-keystore-info"/>
    </target>

    <target name="update-keystore-info">
        <for list="${modules}" delimiter=":" param="cur" trim="true">
            <sequential>
                <mkdir dir="@{cur}/nbproject/"/>
                <!--Place the information in the properties file-->
                <propertyfile file="@{cur}/nbproject/project.properties">
                    <entry  key="keystore" value="../${keystore.location}${keystore.name}"/>
                    <entry  key="nbm_alias" value="${keystore.alias}"/>
                </propertyfile>
                <mkdir dir="@{cur}/nbproject/private/"/>
                <!--Place the password in the private properties file-->
                <propertyfile file="@{cur}/nbproject/private/platform-private.properties">
                    <entry  key="storepass" value="${keystore.password}"/>
                </propertyfile>
            </sequential>
        </for>    
</target>

The script use ant-contrib library so make sure to have it available.

You can import it using one of the following:

1. If the ant-contrib-x.jar is in ant directory:

<taskdef resource="net/sf/antcontrib/antcontrib.properties"/>

2. Otherwise:

        <taskdef resource="net/sf/antcontrib/antcontrib.properties">
            <classpath>
                <pathelement location="path/to/ant-contribx.jar"/>
            </classpath>
        </taskdef>

Also you'll need this values defined in your suite's project.properties file:

keystore.dname=CN=x, OU=x, O=x, C=x
keystore.location=x/
keystore.name=x
keystore.alias=x
keystore.password=x

Just replace x with the desired value.

Great! Can you translate that?

Ok, here's a summary:

1. Create a keystore with genkey task.

2. Using the defined module list (${modules} this is defined by the IDE itself) go to all your modules and add the keystore location and alias information in its nbproject/private/platform-private.properties file.

3. Call Netbeans build task so everything keeps going.

Enjoy!

NOTE: If you get an warning about your plugins not being trusted (and you're using self-signed certificates), you need to create and register your own implementation of org.netbeans.spi.autoupdate.KeyStoreProvider which provides access to a truststore into which your self-signed certificate has been imported as a trusted entry. In other words, the keystore (private key) is used at compile time to sign the NBM file, while the truststore (created by exporting the key from the keystore, then importing it into a new store to mark it trusted) is needed at runtime to validate the signature). All of this may not be necessary if you are signing with a certificate issued by a well-known CA.

Applies to: NetBeans 6.8 and above

Can I sign Maven based NBMs I create?

Yes. NetBeans module artifact builder utility will sign your NBM files if you set keystore, alias and password parameters correctly.

API is a general term - an acronym for Application Programming Interface - it means something (in Java, usually some Java classes) a piece of software exposes, which allows other software to communicate with it.

SPI stands for Service Provider Interface. It is a subset of all things that can be API specific to situations where a library is providing classes which are called by the application (or API library), and which typically change the things the application is able to do.

The classic example is JavaMail. Its API has two sides:

• The API side — which you call if you are writing a mail client or want to read a mailbox
• The SPI side if you are providing a wire-protocol handler to allow JavaMail to talk to a new kind of server, such as a news or IMAP server

Users of the API rarely need to see or talk to the SPI classes, and vice-versa.

In NetBeans, when you see the term SPI, it is usually talking about classes that a module can inject at runtime which allow NetBeans to do new things. For example, there is a general SPI for implementing version control systems. Different modules provide implementations of that SPI for CVS, Subversion, Mercurial and other revision control systems. However, the code that deals with files (the API side) does not need to care if there is a version control system, or what it is.

More on API and SPI

Add a line to your manifest, specifying which version of Java you need. E.g. to only run on JDK 6 and higher, not 5:

OpenIDE-Module-Java-Dependencies: Java > 1.6

Note that > really means >=, and that the traditional "internal" version numbers like "1.5", "1.6", etc. must be used despite the new Java naming scheme (JDK 5, JDK 6, ...).

Requesting 5+ is pointless since no recent version of NetBeans runs on JDK 1.4 anyway.

There is also a syntax for requesting a particular version of the virtual machine (as opposed to Java platform APIs) but this is seldom if ever used.

By default, your module will depend on the same Java version as you specify for javac.source, i.e. the version of the Java language your module requires.

The NetBeans module development support permits you to pick a JDK to use for compiling (and running) a module or suite. Obviously you must specify a JDK at least as new as what your dependency requests; it is unwise to specify a newer JDK than that: you might accidentally use some newer APIs without realizing it, making your code not actually run on the declared minimum version.

Applies to: NetBeans 6.x

Platforms: all

If your module uses some external library, you will probably use a wrapper module to make classes from that library available to your module at runtime.

A wrapper module is a module that contains no code; really the only significant thing about it is its manifest, which does two significant things, in addition to the standard module unique ID/version/etc.:

• Has a Class-Path entry for one or more JARs, conventionally in the subdirectory ext/ of the directory where the module is.
• Declares OpenIDE-Module-Public-Packages followed by a list of the packages from the library that other modules should be able to use.

You can use File > New Project > NetBeans Modules > Library Wrapper Module to make a library wrapper.

So a wrapper module acts as a proxy to turn a library into a NB module. Since you can't modify the NetBeans classpath directly (DevFaqNetBeansClasspath), nor would you want to, this is the way you let your code use third-party libraries. It serves the same function that running with java -cp or setting CLASSPATH would do in a smaller Java application.

There are other options for packaging libraries described in DevFaqWhenUseWrapperModule.

If the above was confusing, read DevFaqModuleDependencies.

Using a wrapper module for an existing project

If you are developing the library yourself, but decide you want to keep the library project separate from any NB module project, you can do so. Just make a plain Java project for the library and build it; and also create a library wrapper module from its JAR output. Here are two ways to hook them up. The first modifies the project so that when the project is built, it copies the jar to the wrapper module. The second modifies the wrapper module so that the wrapper cleans, builds and picks up the jar.

Method 1

To hook them up (since the library wrapper module wizard just copies the JAR you select), you can make the plain Java SE project build into the wrapper. Say your Java SE project is in e.g./src/suite/libs/foo and your NBM wrapper is in /src/suite/foo-wrapper; just edit /src/suite/libs/foo/nbproject/project.properties to specify e.g.:

dist.jar=../../foo-wrapper/release/modules/ext/foo.jar

Now you can just build the Java SE project and it will update the wrapper's JAR file. Also code completion on anything that compiles against the foo library should "see" sources in /src/suite/libs/foo/src (so long as the Java SE project is open).

Method 2

Here's how to have the wrapper module build/clean the Java SE project and then pick up the JAR from the Java SE project's original location. This method provides source association (even if the Java SE project is not open!). You modify a few things in the wrapper project

1. project.xml
   adjust the <class-path-extension>
2. project.properties
   specify extra.module.files
3. remove the wrapper's release directory
4. build.xml
   to override the release target

The following example demonstrates these steps. harness/README gives the details. See also Issue 70894, which would make it easier.

Example using method 2: Having the wrapper module clean and build the project

With these changes to a wrapper module, build/clean on the wrapper, or on the module suite that contains the wrapper, also does build/clean on the project.

For this example, my-wrapper is a library wrapper module for the JAR file produced by the regular Java project called my-project. my-project and my-wrapper are in the same directory; this only affects relative path specifications and is not a general requirement. This example was created on NetBeans 5.5. If you have jars from multiple projects in a wrapper, then this example is extended by using <antsub> instead of <ant> and a FileSet in the release target's <copy> task.

Only the my-wrapper project needs modification.

First

In my-wrapper/nbproject/project.xml, change <class-path-extension>'s <binary-origin> to reference the jar created by my-project. This change gives code completion with Javadoc and Go to Source when referencing my-project.

<binary-origin>../my-project/dist/my-project.jar</binary-origin>

Make sure a ../src directory (relative to the JAR location) containing the corresponding sources of the library exists if you want Go to Source functionality to work.

Second

In my-wrapper/nbproject/project.properties specify where my-project's JAR file is installed in the suite's cluster. This puts my-project.jar in the wrapper's NBM; it is needed since the wrapper's release directory is no longer used as a staging area.

extra.module.files=modules/ext/my-project.jar

Third

Delete the directory my-wrapper/release. The original JAR file was copied here when the wrapper was created. It will interfere if it is left around.

Fourth

In my-wrapper/build.xml add the following. Customize the first two properties' value= to specify your project's relative location and JAR. The release target is replaced; now it builds my-project then copies the JAR to the suite's cluster. The clean target first cleans as usual, then cleans my-project.

<property name="original.project.dir" value="../my-project"/>
<property name="original.project.jar"
          value="${original.project.dir}/dist/my-project.jar"/>

<target name="release">
    <echo message="Building ${original.project.dir}"/>
    <ant dir="${original.project.dir}" usenativebasedir="true"
         target="jar" inheritall="false" inheritrefs="false"/>
    <echo message="Done building ${original.project.dir}"/>

    <copy todir="${cluster}/modules/ext"
          file="${original.project.jar}"/>
</target>


<target name="clean" depends="projectized-common.clean">
    <echo message="Cleaning ${original.project.dir}"/>
    <ant dir="${original.project.dir}" usenativebasedir="true"
         target="clean" inheritall="false" inheritrefs="false"/>
    <echo message="Done cleaning ${original.project.dir}"/>
</target>

How do I include native libraries (*.so or *.dll) in my library wrapper module?

Some libraries come with a native counterpart. The current Library Wrapper wizard doesn't cater to this. As per the JNI section in this document, you simply need to create a lib directory under <my-wrapper>/release/modules (which gets created by the wizard), alongside the ext directory mentioned earlier in this document. This directory is where you place your native libraries.

How do I include more that one jar in my library wrapper module?

With the library wrapper creation wizard it's possible to choose more than one jar (use the CTRL key to select more than one file in the file dialog). Or enter absolute file paths divided by the path separator (e.g. ; for windows systems) into the (very small) file input field.

To add later more, use the project's properties dialog.

Applies to: NetBeans 6.8 and later

The New Module Wizard offers easy support for creating a wrapper module: File > New Project > NetBeans Modules > Library Wrapper Module and since NetBeans 6.8 it is similarly easy to either edit Library Wrapper Module after it has been created or package library directly to your module via Project Properties > Libraries > Wrapped JARs.

Before NB 6.8 it was more convenient to create Library Wrapper module due to existence of the wizard, but not Project Properties UI. This biased the answer to this question, but generally there's no harm in using a library wrapper module.

Note that a library wrapper module can wrap more than one external JAR - you do not need to create one for each library. But it is a good idea to create a separate wrapper for each JAR if they come from different projects and might conceivably be used independently.

The general algorithm for making an optimal decision about when to use a wrapper module is this:

• If the library is from some third-party source, and your module is just using it, then

• If it is something very esoteric and your module will be the only module in an installation of NetBeans (or your NetBeans-based app) ever using it
• You are writing only one module that will use the library, or you want to declare the packages contained in your library in the public packages of your module
• If you will never want deliver an update of that library by itself, without delivering an update of your module

• Then you probably just want to package the library directly into your module, as in DevFaqModuleDependencies

• If you wrote the library you want to use

• You might just want to add the appropriate OpenIDE-Module-* entries directly to its manifest and make it a module that way. Remember to list the packages your module will need to export.
• Else, you probably want to read DevFaqWrapperModules

There is a very slight performance penalty to using a wrapper module - it's one more JAR to open and read from, and one extra layer of indirection for the classloader. That is not a reason to avoid using a wrapper module if that's what you need - it really is slight. In a very large application such as the NetBeans IDE, such considerations are more important because there are more JARs, more classloaders, and hence more overhead already.

If you are developing the library yourself, but decide you want to keep the library project separate from any NB module project, you can do so. See Using a wrapper module for an existing project for information and various methods to hook them up for development.

Applies to: NetBeans 6.8 and above

In the spirit of building on the shoulders of giants, NetBeans takes advantage of external libraries which are not developed on netbeans.org. Those libraries are either open-source software, or binary-only software but with liberal licenses. A few examples: Apache Tomcat; JUnit; JavaHelp (runtime); javac compiler; JSR-88 interface classes.

For convenience, these libraries are stored in the same Hg repository as the source code under CDDL/GPL. They are placed in well-known places in the source tree. The license text is associated with the binary file to make it clear which terms and conditions the users/developers must agree to besides being compliant with the CDDL/GPL itself. Only source code covered by the CDDL/GPL (or BSD, in the case of samples) can be hosted in the http://hg.netbeans.org/main/ repository. As the NetBeans Hg tree is growing, we need to initiate stricter rules and check that all external binary files have a correct associated license. There are also several recommendations on avoiding unnecessary additions of binary files into Hg.

The build system will automatically check if all binary files under <nbmodule>/external are stored correctly with appropriate license and all required information. <nbmodule> means NetBeans project module, e.g. external is on same level as nbproject. Failing to do so will result in a broken build!

Questions:

• I need to store some binaries in my own VCS repository. Should I follow same rules as well? No, you do not have to. You can store your binaries under release/modules/ext/, more details are described in harness/README
• My binary is not a library and I need to store it somewhere else. It has been also created under CDDL. Then you should update nbbuild/antsrc/org/netbeans/nbbuild/extlibs/ignored-binaries
• How can I check all is all right? Run ant verify-libs-and-licenses

Here are the rules NetBeans committers must follow when placing external libraries into NetBeans Hg:

• Legal due diligence must be observed before using a new external library, to make sure that the library license is suitable for use in NetBeans.
• All external binaries should be stored under a subdirectory named <nbmodule>/external, and nowhere else. (For the contrib repository, the path will be contrib/<nbmodule>/external.)
• External binaries are versioned in Hg. ExternalBinaries describes how the actual binary content is stored outside Hg, while the Hg repository actually tracks the SHA-1 hash of the binary. ant download-selected-extbins suffices to download all external binaries in a fresh checkout.
• Each external binary should have a corresponding license file stored in the same directory as the binary itself. You will upload the binary itself through the Web form, but will add the license file directly to Mercurial (e.g. hg add external/somelib-x.y.z-license.txt).
• The name of the binary must follow the convention somelib-x.y.z.jar or somelib-x.y.z.zip where x.y.z is the version number. The corresponding license file must be named somelib-x.y.z-license.txt.
• All license files should be in UTF-8 encoding with appropriate line and paragraph breaks. The license file must end with a newline. Lines should not exceed 80 characters.
• The license file should follow a specific format. Details below.

License file format

License files should be in the following format:

Name: SomeLib
Version: 1.2.3
Description: Library for management of some blah blah blah.
License: Apache_V20 [SeeNoteRegardingNormalizedNames]
OSR: 1234 [OSRNumber,ReferToLFIPreviously;SunInternalLegal]
Origin: http://www.xyz.org [WhereFile(s)WereDownloadedFrom]
Files: xyz.jar, xyz-doc.zip, xyz-src.zip [Optional;SeeBelowForExplanation]
Source: URL to source [MandatoryForLGPL,OtherwiseOptional]
Comment: needed until NB runs on JDK 6+ [Optional:WhyIsThisLibraryHere]

Use of SomeLib version 1.2.3 is governed by the terms of the license below:

[TEXTOFTHELICENSE]

As hinted at above, the OSR field refers to a Sun-internal system. Those contributing patches from outside of Sun can leave this field blank. Also note that a single license file may cover multiple JAR files from the same project. For example, if your patch depends on a third-party library distributed under the same license as two JARs, you will only need one license file and can account for both of these JARs in its Files header.

If the Files header is not present, then a license name-x.y.z-license.txt must correspond to a binary name-x.y.z.jar or name-x.y.z.zip. If present, it should list the names of all binaries to which it corresponds.

The header fields are read during the build process and removed. Therefore this information will not appear in the final build or NBMs.

Template-based licenses

If there is template-based license (like BSD one http://www.opensource.org/licenses/bsd-license.php), e.g. the license file has several ad hoc places to be updated accordingly. The template itself should have the license file stored under nbbuild/licenses

'''TAGNAME'''

Template-based licenses stored along with the binary in Hg must have be in original form as they came with binary:

Example BSD License, as it is stored in nbbuild/licenses:

Copyright (c) '''YEAR''', '''OWNER'''

All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name of '''ORGANIZATION''' nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Example BSD License, as it is stored in Hg along with binary:

Copyright (c) 2007, NetBeans

All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name of NetBeans nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

NBM build, managing correct license for NBMs

Required licenses should be listed in project.properties. (There still must be a license along with the binary in Hg.) The new entry will be called extra.license.files, where the license files will be relative to project basedir, e.g.

extra.license.files=external/x-1.0-license.txt,external/y-2.0-license.txt

This will create an NBM with two extra licenses besides the usual CDDL. This also maintains compatibility with the current build system.

As a convenient shortcut for the common case that you simply want to copy some files to the target cluster (but cannot use the release directory since third-party binaries are involved), you may use the newly introduced release.* Ant properties which should be specified in project.properties. Each key names a file in the source project; the value is a path in the target cluster. Any such pair will automatically:

• Copy the source file to the cluster. (No need to override the release Ant target.)
• Cause the target file to be included in the NBM file list. (No need to add to extra.module.files.)
• In the case of release.external/* properties, cause the associated binary to be included in the NBM license. (No need to override the nbm Ant target or add to extra.license.files.)

Example (from the form module):

release.external/beansbinding-0.6.1.jar=modules/ext/beansbinding-0.6.1.jar
release.external/beansbinding-0.6.1-doc.zip=docs/beansbinding-0.6.1-doc.zip

(Note: if you wish for the binary to be in the classpath of the module as a library, you will still need a <class-path-extension> in your project.xml.) You can also use a ZIP entry on the left side and it will be extracted from the ZIP to your cluster:

release.external/stuff-1.0.zip!/stuff.jar=modules/ext/stuff-1.0.jar

Normalized names

There will be a license repository under nbbuild/licenses where all licenses in use should be available. Each license type will be given a unique name: Apache_V11, Apache_V20, etc. This name must be referred to in the License field. This allows us to count licenses and file names and build a 3rd-party README as well as NBMs. Make sure that the license for a new binary is correctly included under nbbuild/licenses. If there is no existing license of the same type, it must be reviewed prior to committing.

NetBeans Samples

If a sample is created for NetBeans itself, it can be packaged into ZIP file and should not be in the external/ folder. To ensure tests correctly skip over it, the owner must add an entry for the binary into nbbuild/antsrc/org/netbeans/nbbuild/extlibs/ignored-binaries and include a brief explanatory comment.

Alternately, it may be preferable to keep the sample files unpacked directly in Hg, and create the ZIP during the module's build process (either directly into the cluster, or into build/classes for inclusion inside the module). This not only prevents tests from warning about it, but can make it easier to update minor parts of a sample and may make version control operations more pleasant.

The sample itself must be covered by the BSD license; the license must be included in every file (excepting binaries such as icons).

Copyright (c) <YEAR>, Sun Microsystems, Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

* Redistributions of source code must retain the above
  copyright notice, this list of conditions and the following 
  disclaimer.
* Redistributions in binary form must reproduce the above
  copyright notice, this list of conditions and the following
  disclaimer in the documentation and/or other materials
  provided with the distribution.
* Neither the name of Sun Microsystems, Inc. nor the names of
  its contributors may be used to endorse or promote products
  derived from this software without specific prior written
  permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE. 

If sample is not created solely for NetBeans, e.g. bundled in a third-party product and covered by a separate license, it must follow the same rules as for any other binary library.

Common mistakes

A binary file has no associated license. (E.g. xyz.jar is missing xyz-license.txt.)

A binary file has an associated license, but does not maintain the naming convention, or has typos. (E.g. xyz.jar with xy-license.txt.)

Licenses are not pure text. (E.g. they contain HTML.)

A binary file is duplicated in several places. Before adding a new library, please make sure that library is not already available in the Hg tree. If it is, check if the version there is suitable for you; if so, communicate with the owner regarding possible upgrades and/or available packages if they are not available. You might need to move the library to a parent cluster as well. If you do depend on such a third cluster, make sure your module is marked as eager, otherwise it will get disabled.

The names of the binary and its license file will change when the binary is upgraded to a newer version. Update project.properties (or, less commonly, build.xml) to reflect this change.

Before moving from my own repository to NetBeans Hg, I used release/modules/ext/ for storing my binary libraries. They need to be moved into external/ unless the library itself is covered by CDDL, build script, licenses etc., must be updated accordingly!

How do I know if some other modules is relying on the source location of my external binaries? Answer: it's not hard to find out. For example, if you want to know who uses httpserver/external, try this (Unix / Bash syntax):

cd nb-main
for f in */{build.xml,nbproject/*.{properties,xml</tt>; \
  do fgrep -H httpserver/external $f; done

Implementation work

Interesting files from build:

1. Current license summary
2. VerifyLibsAndLicenses test
3. CreateLicenseSummary test
4. Unreferenced or overreferenced files

Static verification of Hg

Part of regular build. Only pays attention to Hg-controlled files in the checkout, so can run on a built source tree without becoming confused. Writes results in JUnit format for easy browsing from Hudson.

• Look for *.jar not in */external/ dirs (with some exceptions).
• Every license file has at least mandatory headers.
• Every license file has lines at most 80 characters long, etc.
• For LGPL, must have Source header.
• Check that every external *.jar or *.zip has a matching license. (Or it can be mentioned in Files header of some license.)
• Every binary has a version number in name.
• No binary occurs more than once, under any name (so check by CRC-32 or SHA-1 etc.). (Look inside ZIP files for nested JARs.)
• Every license file's License field refers to something in nbbuild/licenses.
• The file in nbbuild/licenses exactly matches the body of the license file. Whitespace-only changes are permitted, e.g. rewrapping lines to make them fit. For licenses with templates (e.g. BSD License) any tokens between two underscores can match whatever character sequence.

Things done in IDE build

Generate a third-party JAR & license summary. Find every binary in the IDE build which is either present directly in some */external dir or present inside a ZIP in some */external dir. For every such binary, retrieve the license from nbbuild/licenses. Make a single document listing all of the binaries and licenses.

Verify that no such binary is present in more than one place.

Saved as THIRDPARTYLICENSE-generated.txt in development builds.

Things done in NBM build

nbbuild/templates/projectized.xml (netbeans.org modules only) will look up extra.license.files and use them in Info.xml.

release.* properties honored (see above).

Golden files

nbbuild/build/generated/external-libraries.txt is generated directly from external dirs.

Does not yet take account extra.license.files correctly. Also may not be a complete list of libraries.

Applies to: NetBeans 6.8 and above

DLLs or SOs can be placed in the folder release/modules/lib/ in a module project's sources (look in the Files tab). This will make them appear in the final NBM or application in a lib subdirectory beneath where the module's JAR resides. Then just use System.loadLibrary as usual.

API Reference: JNI in modules

Applies to: NetBeans 6.8 and above

Normally modules interact with one another using public packages: a module can (indeed, must) declare which, if any, of its Java packages are intended to be visible to other modules. When you declare a specification dependency on another module, you only get access to the public packages. This kind of dependency looks like this in the JAR manifest (which is normally constructed from nbproject/project.xml in sources):

OpenIDE-Module-Module-Dependencies: some.other.module > 1.5

(requesting version 1.5 or greater of some.other.module) or like this:

OpenIDE-Module-Module-Dependencies: some.other.module

(requesting any version; not recommended).

Occasionally you may find that the author of a module neglected to expose certain classes in public packages which you know (from reading the source code) that you need to use and know how to use properly. The classes are public but not in declared public packages. It is possible to access these classes if you really have to. But you need to declare a dependency on that exact version of the other module, since such classes might change incompatibly without notice in a newer copy of that module. Since such a change could break your module, the NB module system requires that you declare the implementation dependency so that it can verify before loading your module that it matches the other module. The general idea is that if module B has an implementation dependency on module A, the system should not be able to load B unless it has the exact same version of A that B was compiled against. To make an implementation dependency in the manifest, use

OpenIDE-Module-Module-Dependencies: some.other.module = 3

where the "3" is what that other module declared as its current implementation version:

OpenIDE-Module-Implementation-Version: 3

In order to add an implementation dependency, first add the dependency to the project (e.g. click on "Add Module Dependency" from the "Libraries" node or by click the "Add Dependency..." button in Project->Properties->Libraries panel). Make sure you've checked the "Show Non-API Modules" checkbox when you're looking for the non-API module, otherwise you're not going to find it. Then, after you've added the module as a dependency, edit the dependency (either Project->Properties->Libraries->Select Dependency->Edit or Project->Right click on dependency Libraries node->Edit) and just select the "Implementation Version" radio box in the Edit dependency dialog. If you don't want to "see" all packages within the module, but only a subset, uncheck the "Include Packages in Classpath" checkbox and select the packages you want to see. This works best if the other module uses a nonnegative integer for the implementation version, and if you also check Append Implementation Versions Automatically in the properties dialog.

Implementation dependencies are to be avoided unless you really need access to all the classes in another module, for the following reason: If your module has an implementation dependency on module A, and module A is upgraded, your module probably must be upgraded as well, or the system will not load it (assuming module A's implementation version has changed with the upgrade - it should have). It is a particularly bad idea to use implementation dependencies if you do not know what the other module's author's intentions are for keeping the classes you use available and compatible. It is always possible to make an enhancement request asking for the other module to make the classes you want to use available publicly. Do not use implementation dependencies just to have access to one or two some convenience or utility classes in another module - copy them instead, and file a bug report asking for an API for doing what you're trying to do.

Friend dependencies

Friend dependencies are a little different. A module may have an API which its author is not yet comfortable exposing to just anyone - it might not be fully stabilized yet. In this case, the module with the API can declare some public packages, but also stipulate that only a predefined list of "friend modules" are permitted to use them. The friend modules just declare a regular specification version dependency, but unknown modules are not permitted to use any packages from the API module without an implementation dependency.

(Look at the Versioning panel in the API module's project Properties dialog.)

Always prefer friend APIs to implementation dependencies where there is a choice.

Implementation dependencies, Auto Update, and <verifyupdatecenter>

Implementation dependencies cause special problems for Auto Update. (Some background information is available in NetBeans API & Module Versioning Policy / Numbering Scheme for Updates.)

The problem is that when an implementation version of a module published to an update server changes, any modules declaring implementation dependencies on it must also be published, with dependencies on the new version of the base module. Furthermore, the Auto Update client has just one method for deciding whether an NBM on a server is an "update" relative to what you already have installed: if its specification version is larger. So consider the following snapshot of an update center. (The syntax is not what the actual XML file looks like, just an abbreviated version that shows parts relevant to this example.)

[Monday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Implementation-Version: 070120

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Implementation-Version: 070120
OpenIDE-Module-Module-Dependencies: infrastructure = 070120

These two modules were built at the same time and could be installed together into a NetBeans instance. So far so good.

Now consider what happens when the developer of guifeature adds a major new feature and decides to publish a new version, 1.1. The next day's build produces

[Tuesday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Implementation-Version: 070121

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.1
OpenIDE-Module-Implementation-Version: 070121
OpenIDE-Module-Module-Dependencies: infrastructure = 070121

Again, these two modules could be installed together.

But what if a user connected to the update center on Monday and downloaded both modules, and then connects again on Tuesday looking for updates? infrastructure is still listed as 1.0 so Auto Update ignores it (1.0 is "already installed", after all). guifeature 1.1 is however a possible update. What if you install this update? The module system will refuse to enable guifeature because it requests infrastructure = 070121, whereas you have infrastructure = 070120. Oops!

The solution (short of not using implementation dependencies at all) is to use the NetBeans build harness to compute a specification version. The developer removes OpenIDE-Module-Specification-Version from manifest.mf in the source projects for both modules. manifest.mf for infrastructure instead will get

OpenIDE-Module-Implementation-Version: 1

(only positive integers 1, 2, ... are supported!). And nbproject/project.properties for both modules will get the specification version in a new form:

spec.version.base=1.0.0

The IDE's GUI for module projects lets you do all this without editing metadata files manually; just click the option Append Implementation Versions Automatically in the Versioning panel of the Properties dialog.

(The extra .0 is required for modules in the NetBeans distribution. When sources are branched for a release, spec.version.base is incremented to 1.0.1, 1.0.2, ... for each release on the branch. "Trunk" (development) changes increment the first or second digits, e.g. 1.1.0, 1.2.0, ...)

The effect of using spec.version.base is that our AU snapshots now look like this instead:

[Monday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0.0.1
OpenIDE-Module-Build-Version: 070120
OpenIDE-Module-Implementation-Version: 1

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.0.0.1
OpenIDE-Module-Implementation-Version: 070120
OpenIDE-Module-Module-Dependencies: infrastructure = 1

[Tuesday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0.0.1
OpenIDE-Module-Build-Version: 070121
OpenIDE-Module-Implementation-Version: 1

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.1.0.1
OpenIDE-Module-Implementation-Version: 070121
OpenIDE-Module-Module-Dependencies: infrastructure = 1

The update to guifeature is now safe; it can still use infrastructure from Monday. Note the new "build version" tag which is used only for diagnostics, not for dependencies.

If there is actually a change in the signature of anything in infrastructure that might affect guifeature, then the developer merely needs to increment the implementation version in infrastructure/manifest.mf:

[Wednesday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0.0.2
OpenIDE-Module-Build-Version: 070122
OpenIDE-Module-Implementation-Version: 2

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.1.0.2
OpenIDE-Module-Implementation-Version: 070122
OpenIDE-Module-Module-Dependencies: infrastructure = 2

If the user connects to the update center on Wednesday, the wizard will display both modules as needing to be updated - which is exactly what you want.

How is this system enforced? For one thing, attempts to use inherently unsafe implementation dependencies, or incorrect uses of spec.version.base, should produce warnings during the module build process. So look at the output of Ant once in a while and see if the build harness is telling you something.

There is also a continuous builder at http://deadlock.netbeans.org/hudson/job/nbms-and-javadoc/ which (among other things) tries to build NBMs for all modules in the NetBeans standard distribution plus those experimental "alpha" modules normally published on the update center for development builds. If you commit changes to experimental modules this build will be triggered; failures are mailed to broken_builds@netbeans.org, which all developers of modules in netbeans.org ought to subscribe to.

This builder uses an Ant task <verifyupdatecenter> to detect dependency problems among NBMs. There are two checks:

1. Can the NBMs just built all be enabled together? (synchronic consistency)
2. Suppose I had connected to the update center produced by the previous successful build and installed everything, and now I connected again to this build's update center and asked for all updates. Would any updated modules be broken, due to dependencies on new versions of other modules which were not updated? (diachronic consistency)

The second check is what will catch a lot of mistakes in usage of implementation dependencies as described above. Unfortunately it is not feasible to run the second check as part of an offline build process in your own source checkout, as it depends on a build of older sources; so you will need to commit changes and wait for the next build to verify them.

Generally there are two possible solutions to a test failure from this stage:

1. Remove the implementation dependencies; switch to friend dependencies or public APIs.
2. Ensure that all implementation dependencies are against positive integers (not dates), and that spec.version.base is used on both sides of the dependency, as described above.

In either case, to fix a test failure you will generally also need to increment the specification versions of modules on both sides of the dependency.

Applies to: NetBeans 5.x, 6.x

Platforms: all

Normally this should not happen because the module build harness tries to protect you from such cases. Still, if it does happen, it could mean

1. your module is trying to use a class, but your module does not declare a dependency on the module that provides that class ... or
2. you are declaring a dependency on the right module, but you are accessing a class that is not in one of the packages that module says are public (for use by other modules) ... or
3. your module is not a "friend" of the module that provides the class.

If the problem is #1, you need to declare a dependency on the module where the class is (remember that all of NetBeans APIs are modules, and in separate jars - so if it's the IO API, that's a module org.openide.io, if it's the Window System, that's a module org.openide.windows... and so forth).

Setting dependencies is easy - open the Properties for your project, and choose the Libraries page. (Or just get the context menu for the Libraries node under the project in the Projects window.) Click Add and a small dialog opens - just type the name of a class you need to use, and it will filter the list to find the module that provides that class - so you don't have to memorize a huge list of mappings from classes to modules.

If it's problem #2, then you are already declaring a dependency, but to get full access to all classes in a module, you need to declare an implementation dependency (DevFaqImplementationDependency). Be sure you really need to use the class you're trying to use, in this case - it will make your module hard to upgrade because generally it will need to be paired with the exact version of the other module's JAR that it was built with - if that module is upgraded, your module may end up being disabled.

Also check if class you are trying to use from other module is mark as public to outside modules (right-click on module and select Properties, then API Versioning and in Public Packages check whether package of your class is ticked).

Problem #3 may happen if you change your modules name. If some module declared yours as a friend it will no longer recognize it.

Checking for errors eagerly

For a nice way to resolve all module dependencies at once, to force all of the errors to be exposed simultaneously, just add the following to the command line when starting NetBeans:

-J-Dnetbeans.preresolve.classes=true

The message displayed states that when using this flag, you should not use the -J-Xverify:none flag (often specified in the IDE configuration file), so you may need to edit the .conf file to remove the -Xverify option before using the pre-resolve option.

More tips

For help on working with class paths, please see

http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/classpath.html

Applies to: NetBeans 6.x

Platforms: all

A cluster is a directory on disk. A cluster contains modules. If you are writing a small NetBeans-based application, you probably do not need to be too concerned about clusters, although you may encounter the concept if you need to bundle additional files (native executables, for example) with a module. Clusters become important if you are writing an extensible application (or multiple applications) of your own, where you are sharing some common modules between multiple applications.

The NetBeans launcher is passed a list of cluster directories on startup (see $NB_HOME/etc/netbeans.clusters in the IDE - the names in this file are relative paths from the IDE install directory - but they could also be absolute paths on disk). The launcher looks for the modules (JAR files) which it should load in those "cluster directories". A NetBeans-based application typically consists of, at a minimum, the platform cluster and at least one application-specific cluster which contains modules that implement the business logic of that application.

Cluster directories are not necessarily all located under the same parent directory. They just happen to be in a typical NetBeans IDE install.

The NetBeans platform expects cluster directories to have a certain minimal structure:

• There will be a modules/ subdirectory containing module JAR files
• There will be a config/Modules/ subdirectory containing XML files that describe if/when each module should be enabled
• There will be an update_tracking/ subdirectory which contains metadata that allows the module system to determine if another version of each module is newer than, older than, or the same as the one in this cluster, using dates and checksums

A cluster may contain additional files and folders as needed. For example, it is common for modules which bundle 3rd-party libraries to include those JAR files in modules/ext/. A cluster can contain whatever other files a module needs at runtime - for example, a module that installs a mobile phone emulator would probably include the native emulator executable.

To include additional files in your cluster, simply create a directory release/ underneath your module's project directory (not the src/ directory for your module, but its parent folder - the one that is your module project). Anything under $PROJECT/release/ will be copied into your cluster by the build process. To find the file at runtime, use InstalledFileLocator, e.g.

File emulatorBinary = InstalledFileLocator.getDefault().locate(
  "phone/bin/emulator.exe", "com.foo.my.module.code.name", false);

Suites vs. Clusters

The result of compiling a module suite is typically a cluster. A cluster is something the runtime understands; a suite is a a project you develop. For more information see the suite-versus-cluster FAQ.

Why Have Clusters?

Here's the history of clusters:

• Originally, NetBeans didn't have "clusters"—there was just $NB_HOME/modules/, a bunch of JAR files, and some XML files saying what was enabled and what was not. You looked up the installation directory using System.getProperty("netbeans.home")
• Modules are libraries - like any other library or DLL or .so used by applications - and it is normal for multiple applications to use the same copy of some library
• Sun had a number of NetBeans-based applications. So might anyone creating a NetBeans Platform-based application. The platform is the same for all of them; so are some other parts depending on what modules those applications use.
• Some operating systems will not allow you to distribute native OS packages that will clutter up a user's disk with extra copies of files the user already has. The guidelines for Solaris, Debian, Ubuntu and other operating systems, all request or require that, if a library already exists on the target machine, you should use that library in-place, not install your own copy of it. If we wanted Ubuntu and Debian users to be able to type apt get netbeans, we needed to solve this problem for the NetBeans IDE and other NetBeans-based applications.
• The platform, and other parts of NetBeans therefore should be able to be shared among multiple applications and used by them at the same time.
• Therefore, a NetBeans-based application should not assume that all of its parts ("clusters" of modules which interdepend) are underneath the same directory on disk—the platform might be in one directory, while the Java modules are someplace else entirely.
  • Before this, a typical way to find a file underneath a NetBeans install was new File(System.getProperty("netbeans.home")) to get the NB install directory; then you could try to find a file somewhere under that directory.
  • If there is not necessarily an "install directory" at all, then you need something like InstalledFileLocator, which knows about the cluster directories being used in the running application, and can look in all of them. That is much cleaner than you having to write the code to figure out where all of those directories are and look in each one.

In short, while it is typical for all of the parts of an application to be under a common parent directory, that is neither required nor guaranteed.

What Does A Cluster Look Like?

Here is the structure of the (comparatively small - it contains only one module) ergonomics cluster in a NetBeans 6.9 development build.

• ergonomics/ The cluster directory
  • .lastModified An empty file used as a timestamp so NetBeans can cache information about the cluster for performance, but know if its cache is out-of-date
  • config/ Contains metadata about module state
    • Modules/ Contains files which tell NetBeans some things about the module, mostly relating to if/when it should be enabled
      • org-netbeans-modules-ide-ergonomics.xml Metadata about the Ergonomics module, whose code-name is org.netbeans.modules.ide.ergonomics
  • modules/ Directory that contains the actual (multiple) module JAR files and any 3rd-party libraries they include
    • org-netbeans-modules-ide-ergonomics.jar This is the actual JAR file of the Ergonomics module's classes
  • update_tracking/ Contains metadata about the module which is needed by Tools > Plugins
    • org-netbeans-modules-ide-ergonomics.xml Contains installation date, version and CRC checksums of module JAR and enablement data

In a larger cluster, all of the child directories described above would contain one file for each module (i.e. module JAR file, etc.).

Metadata

The metadata in $CLUSTER/config/Modules/$MODULE.xml is fairly simple and straightforward - it enables the NetBeans module-system to determine when a module should be loaded:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//NetBeans//DTD Module Status 1.0//EN"
                        "http://www.netbeans.org/dtds/module-status-1_0.dtd&quot;>
<module name="org.netbeans.modules.ide.ergonomics">
    <param name="autoload">false</param>
    <param name="eager">false</param>
    <param name="enabled">true</param>
    <param name="jar">modules/org-netbeans-modules-ide-ergonomics.jar</param>
    <param name="reloadable">false</param>
</module>

Similarly, the metadata in $CLUSTER/update_tracking/$MODULE.xml contains data about the module generated when it is installed:

<?xml version="1.0" encoding="UTF-8"?>
<module codename="org.netbeans.modules.ide.ergonomics">
    <module_version install_time="1266357743218" last="true"
                    origin="installer" specification_version="1.7">
        <file crc="3871934416"
              name="config/Modules/org-netbeans-modules-ide-ergonomics.xml"/>
        <file crc="1925067367"
              name="modules/org-netbeans-modules-ide-ergonomics.jar"/>
    </module_version>
</module>

This data allows the Tools > Plugins updater functionality to determine if the version of the module on an update server is a newer version than the copy which the user has installed, so that it can decide if it should offer an update. More importantly, since this is done with checksums, it can do this check without sending data about what is on the user's machine to a remote server, users privacy is maintained.

Clusters and Compatibility

A cluster is a compatibility unit and has a version. It is set of modules that is developed by the same group of people, built and released at one time.

Most of the reasoning that lead to creation of the concept can be found in: Installation Structure

A suite is a project which bundles together a number of module projects, lets you build them all together, and puts the resulting JARs in a directory structure the NetBeans Platform understands.

That directory structure is a cluster. A cluster is a directory structure which the application launcher and module system understand. A cluster is a runtime artifact where the module system can find the modules that make up an application.

While it is common to think of a suite as being a cluster (the build product of a suite is a cluster, after all), they are not the same thing.

Suites

A suite is a container project used to group module projects into a unit whose members can depend on one another, and also depend on a copy of the NetBeans platform.

The structure generated on disk when you compile a suite project is a cluster.

If you are creating a single module (perhaps an IDE extension or a very simple NetBeans Platform-based application) you can ignore suites, and just build/run/distribute a single stand-alone module. You will still get a cluster structure on disk when you compile the module. However, suite projects offer some additional features, such as building zip and JNLP application distributions.

You can always start with a stand-alone module project and later create a suite project and add your module to the suite. If you are going to bundle multiple third-party libraries, and want the ability to provide updates of those libraries, you probably want a suite.

Inter-suite Dependencies

A suite may depend on

• Another suite
• A stand-alone module
• An external binary cluster (a cluster directory somewhere on disk which you might not have the source code to: DevFaqWhatIsACluster). Use the Add Cluster button on the Libraries tab of your suite's Project Properties dialog to set up such dependencies.

See DevFaqHowToReuseModules for more details.

Clusters

A cluster is typically a subdirectory of a NB-based application's binary installation. Every module in the installation lives in one (and only one) cluster. For details on the structure of clusters, see DevFaqWhatIsACluster.

The installation is divided into clusters for purposes of:

1. Conceptual clarity.
2. Mapping to native packaging systems such as RPM, Debian/Ubuntu packages, Solaris packages, etc.

The NetBeans team has a policy of treating inter-cluster module dependencies as more significant than intra-cluster module dependencies with respect to backward compatibility. The goal is to make it possible for product teams building on top of the NetBeans IDE to select a subset of the IDE to use—with cluster granularity rather than with module granularity.

Cluster-granularity is simpler to grasp and integrate with native packaging (if the NetBeans IDE consisted of 500 Debian packages, nobody would be particularly happy about that). But there is nothing preventing you from reusing a subset with module granularity.

The NetBeans launcher (nbexec) accepts a list of cluster directories to load modules from—basically a search path. There are no further semantics to clusters.

The suite project type has a standard build target to assemble a complete application. For simplicity, it simply places all modules built from suite sources into their own cluster named in accordance with the suite's name.

NBMs may specify a cluster. The netbeans/ subdirectory of the NBM (which is a ZIP file) has a file layout which matches the layout of files within a single cluster. Each cluster managed by Auto Update has an update_tracking/ subdirectory with one XML file per module, enumerating the files which that module contributes to the cluster.

Currently the "NB Platform" is just the platform cluster from the IDE. The entire contents of the platform cluster may not be exactly what you want for every "platform" application, so a suite project allows you to exclude modules you do not wish to include.

Clusters are supposed to be medium-grained or coarse-grained, unlike modules which are generally fine-grained units.

See also:

• harness/README in your IDE distribution
• the Help > Contents pages on modules and applications
• http://platform.netbeans.org/articles/installation.html

No Suites In NetBeans IDE Sources

The NetBeans IDE build (from sources on hg.netbeans.org) does not use suites.

It uses a historical build infrastructure which partially overlaps the external module/suite build harness introduced in NetBeans 5.0, but which has different requirements, and is considerably more complex.

Module projects physically inside the netbeans.org source tree cannot be "standalone" modules nor "suite component" modules. They are simply netbeans.org modules, and as such use a (slightly) different format for metadata, and have access to somewhat different facilities specific to netbeans.org practices.

The resulting build artifacts are, nonetheless, clusters. These clusters are simply built using a different build-infrastructure, where the cluster names and contents are defined in .properties files in $NB_SRC/nbbuild/.

Assuming you are using version 6.8 or later, this is supported by the module development infrastructure:

1. Open Suite B in the IDE
2. Right-click on Suite B in the IDE
3. Click properties
4. Click libraries on the left of the suite properties dialog
5. Click 'Add project...' at the bottom of the suite properties dialog
6. Locate the directory containing the source code for Suite A

You can then select which modules from suite A you want to include in suite B.

Source: posting by Tom Wheeler

I want to use modules from update center in my RCP applications. How to do it?

It's possible to use non-netbeans.org modules (yours or 3rd party) directly in your suite and perform this configuration via the GUI. To do this, go to the Properties of your suite project, Libraries tab:

[image - see online version]

If you have sources of modules you want to reuse, click Add Project... button and browse for the suite or standalone module project you want to add.

If you want to use 3rd party binary modules, just unpack them into a cluster folder somewhere on your disk. Preferably put the cluster under your suite's root so that you can use relative paths, which makes setup in a team environment easier. Then click the Add Cluster... button and browse for the cluster folder:

[image - see online version]

You can also add sources and/or Javadoc for binary modules, just like for the whole NetBeans Platform.

Once projects and clusters are added to Libraries and checked, they behave just like part of the platform. They will appear in running platform application, will be included in binary distribution, modules from your suite can depend on them, etc.

I cannot use 6.7 or newer platform, what to do?

You can actually use older platform as long as you configure it to use newer harness (either via Tools -> NetBeans Platforms in IDE or by specifying harness.dir) and you develop in new enough IDE.

If you cannot even use new harness and/or IDE, you have to use suite chaining, build your own platform and depend on it. See harness/README file for details. See also HowToReuseModules.

I want to use modules installed in my IDE in my RCP applications. How to do it?

First make sure that you have the IDE to install the downloaded plugins into shared directories. To do this go to Tool>Plugins then the Settings tab. Enable the check box at the bottom in the advance section. You might be warned about not having permission to save files into a location. Just make sure to run NetBeans as an administrator.

Now install the plugins you are interested in (using the Update center or manual install). They'll be installed in a different place within the NetBeans platform depending on the classification of the plugin. Verify in the platform, you might have a new cluster named extra.

See also

• Where is the Platform and how can I build it? for more details on how to add a custom platform for your application so the project is stand alone.

Using an Update Center for a Stand Alone Module

This was suggested as a patch but rejected (https://netbeans.org/bugzilla/show_bug.cgi?id=185283)

Add the following to the module's build.xml file:

<target name="create-update-center" depends="harness.taskdefs, nbm">
        <mkdir dir="${update.dir}"/>
        <pathfileset id="updater.jar">
            <path refid="cluster.path.id"/>
            <filename name="modules/ext/updater.jar"/>
        </pathfileset>
        <makeupdatedesc desc="${update.dir}/updates.xml" distbase="."
automaticgrouping="true" uselicenseurl="${use.license.url.in.catalog}">
            <fileset dir="./build">
                <include name="*.nbm"/>
                <include name="*.jar"/>
            </fileset>
            <updaterjar>
                <resources refid="updater.jar"/>
            </updaterjar>
        </makeupdatedesc>
        <!--Copy the files to the folder-->
        <copy todir="${update.dir}">
            <fileset dir="./build">
                <include name="*.nbm"/>
                <include name="*.jar"/>
            </fileset>
        </copy>
    </target>

This will create an update center for the stand alone module!

Note: Nothing magic about it. Just used the Netbeans task makeupdatedesc. Feel free to change the target name and change ./build with something smarter (I couldn't find a pre-defined variable for that in the stand alone modules).

Assuming you are using version 6.8 or later, this is supported by the module development infrastructure:

1. Open Suite B in the IDE
2. Right-click on Suite B in the IDE
3. Click properties
4. Click libraries on the left of the suite properties dialog
5. Click 'Add project...' at the bottom of the suite properties dialog
6. Locate the directory containing the source code for Suite A

You can then select which modules from suite A you want to include in suite B.

Source: posting by Tom Wheeler

I want to use modules from update center in my RCP applications. How to do it?

It's possible to use non-netbeans.org modules (yours or 3rd party) directly in your suite and perform this configuration via the GUI. To do this, go to the Properties of your suite project, Libraries tab:

[image - see online version]

If you have sources of modules you want to reuse, click Add Project... button and browse for the suite or standalone module project you want to add.

If you want to use 3rd party binary modules, just unpack them into a cluster folder somewhere on your disk. Preferably put the cluster under your suite's root so that you can use relative paths, which makes setup in a team environment easier. Then click the Add Cluster... button and browse for the cluster folder:

[image - see online version]

You can also add sources and/or Javadoc for binary modules, just like for the whole NetBeans Platform.

Once projects and clusters are added to Libraries and checked, they behave just like part of the platform. They will appear in running platform application, will be included in binary distribution, modules from your suite can depend on them, etc.

I cannot use 6.7 or newer platform, what to do?

You can actually use older platform as long as you configure it to use newer harness (either via Tools -> NetBeans Platforms in IDE or by specifying harness.dir) and you develop in new enough IDE.

If you cannot even use new harness and/or IDE, you have to use suite chaining, build your own platform and depend on it. See harness/README file for details. See also HowToReuseModules.

I want to use modules installed in my IDE in my RCP applications. How to do it?

First make sure that you have the IDE to install the downloaded plugins into shared directories. To do this go to Tool>Plugins then the Settings tab. Enable the check box at the bottom in the advance section. You might be warned about not having permission to save files into a location. Just make sure to run NetBeans as an administrator.

Now install the plugins you are interested in (using the Update center or manual install). They'll be installed in a different place within the NetBeans platform depending on the classification of the plugin. Verify in the platform, you might have a new cluster named extra.

See also

• Where is the Platform and how can I build it? for more details on how to add a custom platform for your application so the project is stand alone.

Using an Update Center for a Stand Alone Module

This was suggested as a patch but rejected (https://netbeans.org/bugzilla/show_bug.cgi?id=185283)

Add the following to the module's build.xml file:

<target name="create-update-center" depends="harness.taskdefs, nbm">
        <mkdir dir="${update.dir}"/>
        <pathfileset id="updater.jar">
            <path refid="cluster.path.id"/>
            <filename name="modules/ext/updater.jar"/>
        </pathfileset>
        <makeupdatedesc desc="${update.dir}/updates.xml" distbase="."
automaticgrouping="true" uselicenseurl="${use.license.url.in.catalog}">
            <fileset dir="./build">
                <include name="*.nbm"/>
                <include name="*.jar"/>
            </fileset>
            <updaterjar>
                <resources refid="updater.jar"/>
            </updaterjar>
        </makeupdatedesc>
        <!--Copy the files to the folder-->
        <copy todir="${update.dir}">
            <fileset dir="./build">
                <include name="*.nbm"/>
                <include name="*.jar"/>
            </fileset>
        </copy>
    </target>

This will create an update center for the stand alone module!

Note: Nothing magic about it. Just used the Netbeans task makeupdatedesc. Feel free to change the target name and change ./build with something smarter (I couldn't find a pre-defined variable for that in the stand alone modules).

As your code evolves, you may find that it no longer needs dependencies on some modules that it used to require. In this case, you can run the fix-dependencies Ant target on your module to remove any unnecessary dependencies from your project.xml.

As with any automated modification, it's a good idea to ensure that this file is up-to-date in source control before running this task, although in an emergency you can use the IDE's local history feature to revert changes.

Applies to: NetBeans 6.8 and above

Introduction

Normally to work on modules versioned in the NetBeans main Mercurial repository you need to clone the entire repository. (For modules in contrib, you need contrib cloned as a subdirectory of main.) For people interested in just playing with patches to one or two modules this can be onerous, however. As an alternative, you can work on "orphan" modules from the netbeans.org source base (Issue 143236 has details). There are two issues to consider:

1. Mercurial currently does not let you clone or check out just a subdirectory of a repository, so you will need to get module sources some other way (we are still considering some possibilities).
2. Since "upstream" modules (that the module of interest depends on) are not available in source form, you need to have a recent development build of NetBeans available to compile against.

Quick usage guide

1. Create an nb_all dir wherever you like. It must have at least the nbbuild dir from the netbeans.org source tree.
2. Create nbbuild/user.build.properties and in it set the property netbeans.dest.dir to the full path to a NetBeans IDE installation you would like to both compile against and build into (you should not use your real development IDE, rather a copy).
3. Run: ant -f nbbuild/build.xml bootstrap
4. Add subdirs for any netbeans.org module projects you would like to work on. (The modules may be already present in the target platform. If they are not, you need to check out sources for any transitive dependencies not in the target platform too.)
5. Using the IDE, open the desired projects and work normally.

What works

Source projects should open without error and without displaying error badges, assuming all dependencies are available in either source or binary form.

You can build the projects normally. The modules will be built into the target platform (overwriting any existing copy of the module).

You can use Run and Debug to start the target platform with a test userdir after building the modules, set breakpoints etc.

You can Test the source projects normally.

Code completion should work against APIs present in other modules. If those modules are available in source form, you will get popup Javadoc automatically, and can navigate to sources. If not, you can still add popup Javadoc capability for all published APIs:

1. Download "NetBeans API Documentation" from AU.
2. Open NetBeans Platform Manager.
3. Select the "default" platform and note the location of NetBeansAPIDocs.zip in the Javadoc tab.
4. Create a new platform; select the same dir as you specified for netbeans.dest.dir.
5. In the new platform, add NetBeansAPIDocs.zip to the Javadoc tab.

Caveats

• If you want to work on unit or functional tests, you need to have all test-to-test dependencies available as source projects, because we do not distribute test libraries. Sometimes the transitive dependency tree can get a bit big. For example, if the functional tests use org.netbeans.junit.ide.ProjectSupport, then you need to check out java.j2seproject (in whose unit test dir this class resides), then its dependencies in turn: projectapi, projectui, openide.filesystems, and openide.util. Test-to-module dependencies (e.g. nbjunit, jellytools, ...) can however be satisfied from the target platform's binaries.

• If you add new source modules to the tree, you will need to both restart NetBeans and delete the nbbuild/nbproject/private/ dir in order to reset all caches and ensure that the new sources are recognized.

• Various targets in nbbuild/build.xml not used in the above scenarios may or may not work usefully, though this should not affect routine module development.

• The target platform needs to be new enough to support any API calls you are making from source modules into binary modules. If the platform is older, you could see error badges. Besides getting a newer platform, this can be corrected by adding sources of the new version of the API module to the tree.

• Note that the bootstrap ant target will not work if you just copy nbbuild from the netbeans.org source tree into nb_all. Other than nbbuild you also need to copy directories:
  1. ide/launcher
  2. javahelp
  3. apisupport.harness

Applies to: NetBeans 6.8 and above

Yes. See the JavaHelp Integration API which describes how to include JavaHelp documentation in a module under Help > Contents; and you can provide rich context help rather easily, linking into the same documentation.

There is an IDE wizard for creating a help set for your module.

Applies to: NetBeans 5.x, 6.x

Platforms: all

The O'Reilly book is old (written between 2001 and 2002) - the chapters on architectural background will still work, but many of the examples won't.

The generation of NB it was written for is from before Lookup (see DevFaqLookup) was in use. TopManager was a class with a bunch of static methods for getting service objects. It is now gone.

For pretty much everything available via TopManager, simply take the class you were looking for and try SomeClass.getDefault() - that's typically the modern way to do this sort of thing. TopManager caused a tangle of interdependencies between different APIs that it was very desirable to remove.

If you were calling TopManager.getDefault().getPlaces().nodes().projectDesktop() in a NetBeans 3.x based application, there is no direct equivalent in NB 4.0 and later. Rather, there is a rich set of project-related APIs which can be used for various purposes. As a rule, there is no 1-to-1 conversion from the above idiom to NB 4.0+; the affected O'Reilly examples would need to be rewritten to make sense today.

Applies to: NetBeans 4.0+

No. Not if you want your module to work in the future. Copy the code instead. If it is a thing that seems generally useful, file an enhancement request requesting an API for the thing you need to do (and make sure there isn't already a supported way to do it).

Anything under org.netbeans.core is non-public, not an API, and subject to change without notice. An API is a contract - an agreement about compatibility. There is no such contract for this namespace, under any circumstances. The class or method you are using may not even exist in the future. Depend on it at your peril.

A perfect example of why not to do this is JProfiler's plugin for NetBeans - it broke very badly across releases because it needlessly depended on the implementation of DialogDisplayer rather than on the API class - so when that class moved, it could no longer link, so the module didn't work.

If you really must use some non-API classes to do what you need to do, use an implementation dependency (DevFaqImplementationDependency) - your module probably won't load in any version except the one it was built against, but at least your users won't get nasty surprises. And ideally, notify the maintainer of the thing you're depending on - they can give you a heads-up if they think they're about to make a change that will break your module.

Applies to: NetBeans 6.8 and above

There are a few cases where NetBeans has convenience classes or facilities that you should use, instead of doing them the way you may be used to. They are:

• Loading images - Don't use ImageIO.read() or Toolkit.loadImage() - instead, use ImageUtilities.loadImage() - it has an optimized image caching strategy, and will play nicely with NetBeans module class loaders
• Creating icons from images - Rather than use new ImageIcon(someImage), use ImageUtilities.image2Icon(someImage) which manages memory better.
• Loading resource bundles/localized strings - Don't use ResourceBundle directly - instead, use NbBundle.getMessage() - it will play nicely with NetBeans class loaders, and Strings resolved this way can be branded using the standard branding mechanism (this is the way you change the title of your application from "NetBeans" to something else). Also, do not hold a reference to a resource bundle - just call NbBundle.getMessage() every time - bundles are cached for a period of time, the call is fast. In a large application, holding resource bundles eats memory wastefully
• Assigning mnemonics to labels and buttons - use Mnemonics to assign text and mnemonic to a widget with one call using one key value pair in properties file and annotate the mnemonic with & character. Also do not reuse the same text if it is used in different UI components. This is more freindly to localization.
  Tip: Check 'Generate Mnemonics Code' checkbox in properties of your form if you are using NetBeans GUI editing support.
• Showing dialogs - instead of creating a JDialog and showing it, or using JOptionPane, use NotifyDescriptor or DialogDescriptor to define your dialog and its contents, then pass these to DialogDisplayer.notify - such dialogs will play nicely with NetBeans' windowing system, global actions, etc.
• Reading/writing/listing files - in most cases, rather than work with java.io.File, you will want to work with org.openide.filesystems.FileObject.

• Quiting application - you can of course still continue to quit using System.exit() but polite NBP apps should employ LifecycleManager instead. Typical Usage pattern is LifecycleManager.getDefault().exit() that is equals to System.exit(0) you don't provide custom LifecycleManager.

Applies to: NetBeans 6.8 and above

If you need to patch an existing module, you can place a JAR file relative to the original. For example, to patch ide/modules/org-openide-example.jar you make a JAR like ide/modules/patches/org-openide-example/mypatch.jar. The mypatch part of your JAR file patch can be named anything you like. The JAR file should only contain those classes you want to patch. It does not need a manifest, though an empty manifest is harmless.

The patch must be in the same cluster as the original. (Issue 69794) If you want to create an NBM containing a patch, you must ensure it will be installed in the same cluster (use the nbm.target.cluster property), but note that you cannot test such a dummy module as part of a module suite (since this property is interpreted only by Plugin Manager). If you are distributing a complete application including a patch to the NB Platform, you will need to either manually preinstall the patch JAR in your copy of the Platform; or override your build-zip target to include the JAR in the final ZIP (in which case testing using Run Project will not have the patch active).

Applies to: NetBeans 6.x

Yes, you can use a pristine platform download (or platform built from sources) and use an external harness from another platform version without sacrificing repeatable builds.

The simplest way to set this up is to use Tools > NetBeans Platform Manager in IDE add/switch to the platform you want to change and select harness on Harness tab. Note that in-IDE module development support defaults to using the harness included with the IDE, ignoring the harness bundled with the platform. You can also configure your module or suite manually to use a specific harness location. As described in harness/README set up a relative path for the platform, but make the harness separate, e.g.

suite.dir=${basedir}
netbeans.dest.dir=${suite.dir}/../nb_sources/nbbuild/netbeans
# Rather than:
#harness.dir=${netbeans.dest.dir}/harness
# use:
harness.dir=${suite.dir}/../special-harness

All NetBeans modules should behave responsibly with regard to performance. They must not affect startup time negatively, they must not increase memory footprint significantly, and they must be responsive at all times.

• startup - module initialization should be as lazy as possible, not to increase startup time
• memory footprint - heap space allocated by module's data structures should be freed as soon as not needed; excessive caching of data is not good
• UI responsiveness - a module's actions, menus and windows should satisfy the UI responsiveness guidelines as stated in UI_Responsiveness

Applies to: NetBeans 6.5 and above

Platforms: All

To disable assertions or set some other VM property for your application, there are two places to pay attention to. First, $APP_HOME/etc/*.conf in your distribution should set things for users of your application - do this for things that should be set for any user.

You also will probably want to test these settings - and *.conf is not going to be used when you launch your application by running your project from Ant (nor the NetBeans IDE). So to handle this, you can set any of the properties documented in $NB_HOME/harness/README. For example, to disable assertions when testing your application from the IDE, edit your module suite's nbproject/project.properties to include run.args.extra=-J-da or similar.

See $NB_HOME/harness/README in your copy of NetBeans for the full list of properties that affect how NetBeans-based-applications are run when developing them in the IDE.

Applies to: NetBeans 6.5 and above

The first problem is to identify what is the root problem causing memory to not be used effectively. The usual approach for this is to analyze the complete contents of memory when the problem appears, using one of a number of appropriate tools, and ideally then find a solution.

Below are some hints on how to analyze the content of memory:

jmap and built-in dumpers in JDK

Obtain the dump.

If the problem causes OutOfMemoryError, it is possible to customize the JVM to provide a memory dump automatically whenever an OutOfMemoryError is thrown. FaqNetBeansAndOOME describes what options can be used for this. If you are developing modules, it is a very good idea to set the option -J-XX:+HeapDumpOnOutOfMemoryError.

If the memory leak is not so aggresive to fill all the available memory and cause an OutOfMemoryError, it is still possible to use jmap to generate the same dump. Running full GC before you create this dump can be a good idea as it can strip the size of dump file and remove some unimportant objects from the snapshot. You can do this by turning memory toolbar on (do a right click in toolbar area and check Memory). Repeating this several times can even collect large amounts of data held in various caches through soft or weak references and make it easier to browse the dump.

Analyze the problem.

Once you have the dump of the heap in a file, it is possible to open it using the NetBeans profiler. This has a number of analysis features and is integrated with the IDE, e.g. to browse sources.

Alternately, you can use the JDK's tool jhat. It will start simple web server and you can use a web browser to see the data. There are many functions starting with lists of classes with numbers of objects and their size, navigation between references, finding of reference chains from GC root to certain objects. JavaScript can be used to express more complex queries.

Other tools

INSANE is a home-grown tool that is useful for analysis of memory content and also can be used in automated tests - so once you have fixed a memory leak, you can write a test that will fail if the memory leak is ever recreated. NbTestCase.assertGC is all you need to know. See also FitnessMemoryLeaks.

Timers/counters module can be used to register objects of interest in the code, then inspect them during IDE run via Runtime Watches window.

Advanced: DTrace can be used to monitor object allocation and garbage collection. Nice article about using DTrace with the HotSpot provider: Java and DTrace.

Tips and tricks

Common leaking objects

There are some typical classes where it should be easily possible to tell what the appropriate number of their instances in memory should be, and if these are leaking there is a serious problem:

• Projects - it means instances of all subclasses of org.netbeans.api.project.Project
• Editors (or TopComponents) - it can be useful to check for org.openide.text.QuietEditorPane instances to see if closed editors can release substantial part of associated memory. If the editor component is held it often means that associated editor support is held too linking to parsing data, sidebars providing versioning information and probably also project metadata. It is also possible to look for instance of org.openide.windows.TopComponent if there is some suspicion or better to search for its particular subclasses. Generally there will be always certain numbers of TopComponents.
• Documents - somewhat related to editors. An important class where you can start is org.netbeans.modules.editor.NbEditorDocument.
• Top-level windows - undisposed dialogs can be a problem as these hold native resources that can be limited in the system.
• ClassLoader - we need to be very careful and check that class loaders created dynamically during runtime can be GC'ed when they are no longer used. Without this the result is OOME signaling that perm gen area is full.
• CompilationInfo (java.source module) - related to Java infrastructure. An important class where you can start is com.sun.tools.javac.code.Symtab, which is a singleton in a javac instance.

Leaks vs. retained memory

There are two different ways how memory can be wasted: leaks and improper retention of memory.

Leaks are cases when repeated invocation of certain activity creates new set of objects that cannot be reclaimed after activity is finished. The biggest problem is accumulation of these objects that leads to increased memory usage and after a long enough time leads to OutOfMemoryError. The nature of this error is that it leaves data structures of an application in undefined state so anything executed after this moment may lead to unexpected results.

Retained memory is memory occupied by objects that were created to serve some purpose but these objects are held longer than necessary. This may mean that some action has to be performed that flushes these objects or they will remain in memory until the end of the session. An example of the former is LRU caches (often holding last component in UI, files or projects). A common example of the latter is resources like parsed bundles or images statically referenced in classes that use them.

-J-Dnetbeans.debug.heap can make profiling easier as it more quickly releases references to collapsed nodes.

If you have the Timers module enabled (normally it is in dev builds), click its button in the Memory toolbar to get a summary of interesting live objects and statistics.

Applies to: NetBeans 6.5 and above

Platforms: All

When we run the module from NetBeans IDE and we want to pass JVM options to increase PermGen and Heap Memory then add the following settings to the project.properties file of your module, or module suite.

run.args.extra=-J-Xmx512m 
-J-XX:+UseConcMarkSweepGC 
-J-XX:+CMSClassUnloadingEnabled 
-J-XX:+CMSPermGenSweepingEnabled
-J-XX:MaxPermSize=256m

Please write the complete setting in one line.

When you attach a listener to another object, via, for example, an addPropertyChangeListener() method, that other object now holds a reference to that listener.

In Java, any object that is referenced by another object which is still in use (i.e. referenced by something else that is still alive, and so forth) cannot be garbage collected. One of the most frequent sources of memory leaks in Swing applications is attaching a listener to some long-lived object and never detaching the listener. The entire object graph of the listener and anything it references is held in memory, whether it is needed or not, until the object being listened to is finally garbage collected.

Since listeners are often implemented as inner (non-static) classes of some other object, and an inner class keeps a reference to the object that created it, the outer object instance is kept in memory too.

WeakListeners is a factory class which wraps your event listener in another one, but it only weakly (using java.lang.ref.WeakReference) references your actual listener. That means that, even though you are listening for changes, that will not block your listener from being garbage collected if nothing else still references it.

There is one caveat to using WeakListeners - if you do something like this:

someObject.addPropertyChangeListener(WeakListeners.propertyChange(new PropertyChangeListener() {
   public void propertyChange(PropertyChangeEvent evt) {
     ...
   }
}, someObject);

in fact you are not listening on someObject for any amount of time - the anonymous PropertyChangeListener you created will be instantly garbage-collected. So keep a reference to your listener when using WeakListeners.

You should use a WeakListener any time you are adding a listener to an object, but there is no code - and possibly no opportunity - to explicitly remove it.

If the thing you are listening to does have some kind of observable life-cycle, it is preferable to explicitly add and detach listeners.

But in the case that you are adding a listener which is never explicitly removed, it is good form to use WeakListeners

There are many possibilities how to profile Java applications and that can be applied to NetBeans profiling. For different task it can be good to select different ways because each of them has its strengths and weaknesses.

See also: DevFaqMemoryLeaks

To be able to profile an application it is usually needed to start it with a modified command that typically adds some (JVMPI or JVMTI) libraries, some classes to (boot)classpath, specifies options for profiling and often initializes profiling support before the application starts to run its code.

NetBeans profiler

The NB module development support is integrated with the NB Profiler. Just select a module and click Profile to start.

Want to cover some typical activities like:

• action execution (invoked from menu or by shortcut)
• window/dialog opening/closing
• use of editor including tracking what happens in background
• startup

Analyzer

It is a sampling profiler working on Solaris and Linux (with limited functionality) that collects data during runtime. These data are later available for offline processing.

It provides some capabilities that are not available in other Java profilers namely timeline view. This view shows timeline for each thread visualizing if the thread actually executes some code or not.

Download and install Analyzer tool

Performance Analyzer that is part of Sun Studio tools and can be downloaded from the developers' site.

Run the Analyzer

• Set the environment. PATH should contain bin directory of Analyzer installation. LD_LIBRARY_PATH should similarly contain lib dir (and also /usr/lib/lwp if you want to run it on Solaris 2.8). Optionally you can also set MAN_PATH. Set the _NB_PROFILE_CMD:
  

export _NB_PROFILE_CMD='collect -p 1 -j on -S off -g NetBeans.erg  -y 38 -d /export/home/radim/analyzer

-p num stands for sampling period (on, hi, lo are also accepted), -j on turns on Java profiling, -y num determines the signal to trigger profiling on/off. -y num,r means that profiling will be resumed at the begining. Use man collect to get detailed explanation of all options.

• mkdir /export/home/radim/analyzer (It is only need first time. Next experiments will be added.)
• Install & start the IDE
• Send signal 38 to Java process to start data collecting (kill -38 $pid). Or use another signal like PROF (this works well on Linux).
• Perform the analyzed activity
• Send the signal again to stop profiling (there can be more evaluated periods during one run).
• Shut down the IDE.
• Run the analyzer to evaluate the experiment in GUI environment: analyzer /export/home/radim/analyzer/NetBeans.x.er

Profiling hints

Startup: start with profiling enabled, send a signal when startup is completed. When sampling every 1ms it takes 70 seconds instead of 40.

Other tools

Quite simple way how to measure time spent in some code is to wrap the code with

long t0 = System.nanoTime();
try {
  ... measured code
} finally {
  long t1 = System.nanoTime();
  System.out.println("action took "+(t1-t0)/1000000+"ms");
}

JVMTI is powerful interface that allows to write custom libraries that will track behavior of application.

DTrace is a comprehensive dynamic tracing framework for the Solaris™ Operating Environment. It is one of the few tools that allows to track activities running deeply in the system and analyze the system. Because there are also probes provided by Java VM and function like jstack it is also possible to map observed actions to parts of Java code in running application.

Tips and trick

Node pop-ups: interesting starting point is o.o.awt.MouseUtils$PopupMouseAdapter.mousePressed()

How to measure performance/responsiveness?

See What is UI responsiveness for overview.

Older Performance web page contains few links to documentation of one possible approach how to measure and profile responsiveness. This is based on use of modified event queue and patches classes from JDK.

Recently we changed the support a bit to avoid modifications of core JDK's classes and and use small utility library available in Hg. This is used in current automated testing and can be used for manual checks too. To run such test:

1. Build performance project.
2. Copy the JAR file to netbeans/platform/core
3. Start the IDE with -J-Dnetbeans.mainclass=org.netbeans.performance.test.guitracker.Main -J-Dguitracker.mainclass=org.netbeans.core.startup.Main
4. ... watch process output when you perform an action

Applies to: NetBeans 6.5 and above

If you set the system property netbeans.full.hack to true, the following IDE behaviors will be disabled to make it quicker or more reliable to test other functionality:

• Auto Update background check (to see if updates are available); you can still use AU via Tools > Plugin Manager
• prompting about still-running tasks when shutting down
• license dialog
• import of old user directory
• IDE registration dialog
• dialog suggesting that you submit usage statistics
• welcome screen displayed by default and RSS feed refreshed
• blocking dialog when some modules could not be loaded
• use of ~/NetBeansProjects/ for newly created projects (java.io.tmpdir will be used instead)
• resizing gesture submit dialog (SubmitStatus.resize)
• weekly Maven repository indexing (can be configured in Options dialog)
• long package name for default group ID in new Maven project (test used instead)

This property is set by default when you:

• run the IDE from sources using ant tryme
• run the IDE from a netbeans.org module project using Run Project (ant run)
• run a functional test using NbModuleSuite or a unit test using NbTestCase

If you need to test one of the suppressed behaviors (e.g. you are working on the license dialog), just do not set this property. For the ant tryme and ant run cases, add

tryme.args=

to nbbuild/user.build.properties or ~/.nbbuild.properties.

Problem: Customization of the build process is not documented properly

Solution:

• Add the custom tasks in the suite's build.xml file
• Add a task overriding the -init task like this:

<target name="-init" depends="suite.-init,custom-task1,...">
        <!--Perform your actions here-->
</target>

The key part is calling the suite.-init task as it initializes a lot of stuff used by the rest of the process. Depending on which things you need to initialize, this target may not work and you may need to pick another one; look at what common.xml in the harness is initializing when.

Applies to: NetBeans IDE 6.8 and 6.9 Platforms: All See also DevFaqSignNbm for an example using this.

You configure such things either in the launcher (netbeans.conf for the NB IDE, some other *.conf for a custom app), or at runtime in a ModuleInstall.

File userDir = new File(System.getProperty("user.home"));
File myProjectsDir = new File(userDir, "My Projects");
if (!myProjectsDir.exists()) {
    myProjectsDir.mkdirs();
}
System.setProperty("netbeans.projects.dir", myProjectsDir.getAbsolutePath());

Source:

http://osdir.com/ml/java.netbeans.modules.openide.devel/2007-12/msg00195.html

I needed to launch the fix-dependencies target on all the modules of my suite, but doing manually is very boring. So I added this target into my suite build.xml that runs the target in each module

<target name="fix-dependencies" depends="-init">

       <subant target="fix-dependencies" buildpath="${modules.sorted}" inheritrefs="false" inheritall="false"/>

</target>

You can change the code so it works with any target.

Applies to: NetBeans IDE 6.5 and newer Platforms: All

There are four basic ways a module can install configuration data or objects. Three of the ways are declarative (DevFaqModulesDeclarativeVsProgrammatic); these mechanisms are preferred.

If you are writing a module that has an API you want other modules to plug in to, you probably want to read DevFaqWhenToUseWhatRegistrationMethod.

@ServiceProvider

For global services, singletons and such, using this annotation is the preferred technique.

What exactly you register is a contract between you and whatever module is providing the interface and will, presumably, do something with what you put there. What's really happening is that you are adding your implementation of this interface to the default Lookup. At build-time, registration files are generated into META-INF/services in your module's JAR file. The default lookup (or JDK 6's ServiceLoader) knows how to read such files. Typically the classes need to be public and have a public no-argument constructor.

Any module can specify interfaces or classes that it would like other modules to implement and register instances of. For example, the Project API module asks that each module that implements a project type (the things you see in the New Project wizard in NetBeans) register their ProjectFactorys in default lookup.

To get an instance of something registered this way, call

TheInterface i = Lookup.getDefault().lookup(TheInterface.class);

If there might be more than one registered object of this type, you can get them all as follows:

for (TheInterface i : Lookup.getDefault().lookupAll(TheInterface.class)) {...}

Registering objects in the System Filesystem

The system filesystem (see DevFaqSystemFilesystem) allows for more detailed configuration when registering objects. It is a virtual filesystem composed of XML fragments (see DevFaqModulesLayerFile) from modules in the system. The top layer of the system filesystem is $USERDIR/config which is where changes that are written at runtime are put.

The system filesystem is composed of folders. Some folders have special meanings to the system; which folders exist and are meaningful depends on which modules you have installed. For example, the core window system defines the folder Menu/, which contains one subfolder for each menu in the main window's menu bar. If you add a file to the folder Menu/File called com-foo-mymodule-MyAction.instance, an instance of com.foo.mymodule.MyAction will be created, and a menu item will be put on the menu for it.

For more details on registering objects, defining an order in which they should appear, etc., see DevFaqModulesLayerFile. In the short form, a module registers a layer by including a line in its manifest:

OpenIDE-Module-Layer: com/foo/mymodule/resources/layer.xml

which points to an actual XML file by that name inside the module JAR file. A layer file is an XML file defining a mini-filesystem:

<filesystem>
    <folder name="SomeFolder">
        <file name="SomeFile"/>
    </folder>
</filesystem>

More and more layer registrations can be made by using various source code annotations. If you use these exclusively, you will not need to declare a layer in your module's sources at all.

Registering objects in the module's manifest

Some types of objects used to be installed by adding a section to the module manifest. This is now deprecated.

Programmatic registration - ModuleInstall classes

The module system allows you to provide a ModuleInstall class, which runs some code during startup or when the module is loaded, and can run cleanup code when it is uninstalled or disabled. This is the least desirable way to do things, because running code on startup means slowing down startup. Before you use such a class, be sure there is no declarative way to do what you're trying to do; see: DevFaqModulesDeclarativeVsProgrammatic

To have some code run on startup/installation/uninstallation/etc., add a line like the following to your module's manifest file:

OpenIDE-Module-Install: org/netbeans/modules/paintcatcher/PaintCatcherModule.class

This line should be part of the group of lines at the top of the manifest, with no blank lines before it. It is a pointer to a class file inside the module. The class file must extend the class org.openide.modules.ModuleInstall. There is a wizard in the development support to create and register such a class for you.

Applies to: NetBeans 6.7 and later

The default lookup is Lookup.getDefault(). It is the registry for global singletons and instances of objects which have been registered in the system by modules. (In JDK 6, ServiceLoader operates on the same principle.) The default lookup searches in two places:

• The META-INF/services/ Lookup contains all objects registered by modules via the Java Extension Mechanism - putting files in the META-INF/services/ directory of their module JARs (typically done using the @ServiceProvider annotation)
• The contents of the Services/ folder of the System (configuration) Filesystem (this is harder and somewhat deprecated)

Objects contained in the default lookup are instantiated lazily when first requested. Objects returned by the default lookup may (or may not) be garbage collected if they become unreferenced.

Here is the usual usage pattern:

1. A central "controller" module defines some interface, e.g.

package controller.pkg;
public interface MyService {
    void doSomething();
}

2. Each module which wants to implement that service depends on the controller module which defines the interface, and creates and registers an implementation:

@ServiceProvider(service=MyService.class)
public class MyImpl implements MyService {
    public void doSomething() {....}
}

It is also possible to declaratively mask other people's implementations and declaratively order implementations so some will take precedence.

3. The controller finds all implementations and uses them somehow:

for (MyService s : Lookup.getDefault().lookupAll(MyService.class)) {
    s.doSomething();
}

More About Lookup

• DevFaqLookup
• Extension Points Tutorial
• Javadoc for Lookup

Applies to: NetBeans 6.7 and later

To run some code when your module is loaded, and basically every time the IDE starts and your module is enabled, simply create a subclass of org.openide.modules.ModuleInstall and override the restored() method. Bear in mind that this is being executing during the time the IDE/platform is starting up. You should limit the work you do here to that which is absolutely necessary.

Once the class is created, you must declare it in your module's manifest.mf file, like so:

OpenIDE-Module-Install: org/netbeans/modules/editor/EditorModule.class

Likewise, to execute code when the IDE is shutting down, you can override the close() method. This method of ModuleInstall is called when the IDE is shutting down, contrary to the closing() method, which is called to alert the module that the IDE is about to shut down. However, another module may veto the shutdown by returning false from the closing() method, so the close() method is best for performing any cleanup work for your module.

You can simply use File > New File > Module Development | Module Installer to create the ModuleInstall class and its registration in the manifest.

Applies to: NetBeans 6.5 and later

Layer files are small XML files provided by modules, which define a virtual filesystem (DevFaqFileSystem). The layer file defines folders and files that will be merged into the system filesystem (DevFaqSystemFilesystem) that makes up the runtime configuration information NetBeans and its modules use.

Layer files help to make it possible for modules to be dynamically installed. If you've read about FileObjects (DevFaqFileObject) and FileSystems (DevFaqFileSystem), you know that you can listen for changes in folders and files in a filesystem. That's exactly what the components of NetBeans whose content is composed from folders in the system filesystem do. So if a module is added at runtime, the system filesystem fires changes; the UI notices that the contents of the folder has changed and updates the UI to reflect the changes.

If you created your module using the IDE, you may already have an XML layer in your module, and you can expand the node for it under Important Files in your module project to see and modify its contents. The way it is declared is simple:

• In your JAR, provide the layer file - e.g. com/foo/mymodule/resources/layer.xml
• In your module's manifest, include the following line somewhere in the top section:

OpenIDE-Module-Layer: com/foo/mymodule/resources/layer.xml

Some Java source code annotations generate layer entries for you (you do not need to have a layer.xml in your module's source tree).

Applies to: NetBeans 6.7 and later

The system filesystem is the central repository for configuration data in NetBeans. It is composed at runtime of a stack of XML layers (DevFaqModulesLayerFile) supplied by modules in the system. Modules use folders in the system filesystem to define extension points - a module can define a folder and document what files or objects (typically instance files: DevFaqInstanceDataObject) other modules can put there, and then, at runtime, scan the contents and do something with the result.

The top layer of the System Filesystem is the config/ subfolder of the user directory. (DevFaqUserDir) That is what makes the System Filesystem read-write - diffs are written there, and there are semantics for programmatically deleting files by creating an empty file called, e.g., TheFile.instance_hidden.

Any type of file can be put into the System Filesystem; what is done with those files is a contract between the module that defines a folder and documents what can be put there, and the modules that put things there. You can use FileUtil.getConfigFile to access entries at runtime.

The same mechanism for file recognition that recognizes user files on disk recognizes files in the system filesystem - so you can put a .java file in the system filesystem, and it can be opened in the editor and edited just as a file on disk can (if saved, it will be written to the user dir on disk, and the newly written file will then be the actual content. In fact, this is why file templates in the IDE can be edited.

Some folders have special meaning to the system, because they are defined by modules that are part of the NetBeans Platform. Some of them are:

• Actions/ - A global repository for actions in the system, it contains subfolders which categorize actions into ad-hoc categories. This folder supplies raw actions for the Key Bindings part of the Options dialog. If you install actions, the typical pattern is to put an *.instance files here.
• Menu - The contents of the menu bar in the main window - it has a folder for each menu; subfolders of these represent submenus, and *.instance files represent Actions to be shown on the menus.
• Loaders - Contains subfolders that define mime types (e.g. Loaders/text/x-java) which are used to define various attributes such as popup menu items that should appear when the user right clicks on a file of a given MIME type.

There are several things which affect how objects are used, all or some of which may be specified by a module's API:

• The location of a file - a module may define a folder that modules put objects directly into, or request that client modules create subfolders in that folder in cases where the entire path to the file has semantic meaning (see below).
• The type of the file - very often you will install *.instance files that represent Java objects; typically the module will specify what classes or interfaces objects in a folder should be assignable from.
• File attributes (DevFaqFileAttributes) - for cases where additional information is required to describe what to do with the files that client modules add to the folder, some optional or mandatory key/value attributes may be specified.

Available documentation on System Filesystem contents

List of files and folders in the system filesystem in NetBeans API Javadoc lists some locations. Feel free to file documentation bugs for modules you know read other locations but which fail to list them in their arch.xml file.

Applies to: NetBeans 6.5 and newer

The layer file browser in NetBeans project support shows the default file system.

Open a NetBeans module project in the Projects window. Navigate to Important Files > XML Layer > <this layer in context>. You can examine the IDE's default file system by browsing the <this layer in context> node.

While browsing the filesystem remember that each node has a "Name" property (use the Properties Window to see the properties of each node). You must use the "Name" to refer to the node in the filesystem.

For instance, in default (English) locale the menu bar appears as the node Menu Bar in the filesystem viewer, but its nonlocalizable code name is Menu. So to refer to the menu bar in your layer.xml file you have to use the name of the node, like this:

<folder name="Menu">

instead of

<folder name="Menu Bar">

Applies to: NetBeans 6.7 and later

*.instance files represent an "instance", i.e. arbitrary Java object.

An instance file typically says what class it is an instance of via its class name - for example, com-foo-mymodule-MyObject.instance. A *.instance file may create its instance from any Java class with a default constructor, or by calling a static method on a class.

In NetBeans infrastructure, *.instance files result in InstanceDataObjects. InstanceDataObjects can supply InstanceCookies, which in turn instantiate the object. So, code to actually get an instance of an object declared in the system filesystem (DevFaqSystemFilesystem) would look like this (plus error checking):

public static Object getTheObject(String pathInSystemFilesystem) throws Exception {
    return DataObject.find(FileUtil.getConfigFile(pathInSystemFilesystem)).
        getLookup().lookup(InstanceCookie.class).instanceCreate();
}

(FileUtil.getConfigObject is available for this purpose in NB 7.1+.)

A much easier way to get all instances of objects in a folder exists:

for (WhatISaidToPutHere instance :
        Lookups.forPath("MyFolder").lookupAll(WhatISaidToPutHere.class)) {
    // ...
}

Note that a default constructor is not required in an XML layer; you can also use a static method, using the following syntax:

<file name="ObjectTypes.instance">
  <attr name="instanceCreate" methodvalue="org.netbeans.core.ui.UINodes.createObjectTypes"/>
  <attr name="instanceOf" stringvalue="org.openide.nodes.Node"/>
</file>

(The instanceOf attribute is optional; it lets the system avoid instantiating your object just to see if it is assignable to Node. This is only useful in folders that contain objects of many different types mixed together, which is normally true only in the semi-deprecated Services folder: code looking for instances of one type only would rather not load everything.)

See also: DevFaqDotSettingsFiles

Applies to: NetBeans 6.7 and later

.settings files are similar to .instance files, with the difference that they are XML format, and can contain serialized data rather than just default instances.

Since the introduction of NbPreferences to replace SystemOption, very little new code uses these files, and they should be considered semi-deprecated. They are difficult and error-prone to use, and have a fair amount of overhead. The Window System still requires them to be used to persist the state of opened windows/tabs (caret position, what file is opened, or other state that should be restored when reopening a TopComponent after a restart) across application runs.

A .settings file can encode the entire parent class and interface hierarchy of the object it represents, so that a query about whether an object of a given type is present (such as using Lookups.forPath("path/to/folder").allItems()) can be answered without actually creating an instance of the object.

Settings files are also useful if you are declaring some objects in a layer file (see DevFaqModulesLayerFile) and intend to write them back out to disk after they have been modified in-memory (note this involves writing ugly and inefficient hexadecimal-encoded serialized data into XML files - if the object is a singleton, using NbPreferences will be both more efficient and more readable).

Example

<?xml version="1.0"?>
<!DOCTYPE settings PUBLIC "-//NetBeans//DTD Session settings 1.0//EN"
                          "http://www.netbeans.org/dtds/sessionsettings-1_0.dtd">
<settings version="1.0">
    <module name="org.netbeans.core.io.ui/1" spec="1.6"/>
    <instanceof class="org.openide.windows.TopComponent"/>
    <instanceof class="org.netbeans.core.io.ui.IOWindow$IOWindowImpl"/>
    <serialdata class="org.netbeans.core.io.ui.IOWindow$IOWindowImpl">
        ACED0005737200296F72672E6F70656E6964652E7...
    </serialdata>
</settings>

*.shadow files are mainly used in the system filesystem for configuration data. They are the functional equivalent of Unix symbolic links - a *.shadow file is a pointer to another file whose behavior in every respect except its path and file name is the same as the original.

*.shadow files are commonly used where only a single instance of an object is needed, but it must be registered in multiple folders. For example, a general Action is declared in the Actions/ folder of the system filesystem. But the action also needs to appear in menus and toolbars, possibly other places. So, rather than create multiple instances of an action, one *.instance file is created in the module's layer file, in the Actions/ folder. Then *.shadow files are created in all of the other places the *.instance file would be needed, pointing to the original file.

Declaring a .shadow file in the system filesystem looks like this:

<folder name="A">
  <file name="com-foo-mymodule-MyClass.instance"/>
</folder>
<folder name="B">
  <file name="Shadow1.shadow">
    <attr name="originalFile" stringvalue="A/com-foo-mymodule- MyClass.instance"/>
  </file>
</folder>
<folder name="C">
  <file name="anotherShadow.shadow">
    <attr name="originalFile" stringvalue="A/com-foo-mymodule-MyClass.instance"/>
  </file>
</folder>

Shadow files can also point to real files on disk. For example, the Favorites tab in the NetBeans IDE uses shadow files to link to real directories on disk.

Creating Shadow Files Programmatically

If you need to create .shadow files programmatically, use DataShadow.create() — do not write FileObjects and try to set attributes on them. In an XML layer, a DataShadow's original file is pointed to by a file attribute. On disk, that is accomplished via the file's content instead. To reliably create DataShadows, let the infrastructure do it for you - do not make assumptions about how the original file is pointed to.

The userdir is a directory passed to NetBeans on startup by the launch script. You can specify it on the command line, e.g.:

--userdir /tmp/some/folder/that/need/not/exist/yet

It contains configuration data that allows NetBeans to restore its state after shutdown; it also contains log files and other miscellaneous artifacts of running NetBeans. The config/ subfolder of the userdir is where changes made at runtime to the system filesystem (DevFaqSystemFilesystem) are written.

Some new modules installed by Plugin Manager will also be installed here, as if it were a "cluster" directory (such as platform or similar in a NetBeans IDE or Platform installation). NBMs which specify a particular cluster name will not be placed in the user directory, however.

It is expected that applications built on the NetBeans platform will provide a custom launch script which will specify the userdir such that it does not overlap with any other platform-based application. This is done for you if you use the stock launchers created by "suite" projects in the IDE.

Only one running copy of NetBeans may use a single userdir at a time; during startup, the platform checks a lock file and if it is present, tries to contact the running instance via a socket, to determine if the lock file is stale or not. If it does not make contact, it will display a warning and ask the user if startup should continue. This same protocol also supports command-line options.

You can find the path to the userdir at runtime if you need to, using the system property netbeans.user. Most modules should not do this; use Places.getUserDirectory to find the userdir or use FileUtil.getConfigFile to work with the config/ subdirectory.

Applies to: NetBeans 6.7 and later

If you are using module development support the IDE, you can manage the order of menu or toolbar items by the help of special node XML Layer which can be found underneath your Important Files. Just find your menu/toolbar item and drag and drop it wherever you need. Appropriate content in the project metadata (layer file) will be generated for you. If this does not work, or you want to know more, read on.

FileObjects (DevFaqFileObject) in a folder have no defined order by default. You can use FileUtil.getOrder to sort them. (DataObjects (DevFaqDataObject) in a folder are always sorted this way.) The order is determined by numeric position attributes. For all details, see: FolderOrdering103187

Applies to: NetBeans 6.5 and later

Yes. This technique is commonly used in platform applications which require the user to log in, to keep menu contents/toolbar actions/keyboard shortcuts/window definitions hidden until the user is authenticated.

There are two ways to do it. The most obvious way is to programmatically write files to disk at runtime (call FileUtil.getConfigRoot().createFolder(), etc.). This technique is appropriate if you are creating files which should be preserved across restarts (for example, adding folders to the Favorites window). It is completely inappropriate in the case of authentication, or any other case where you do not want the added files to be present after restart. You cannot depend on the application always being shut down normally and having a chance to clean such files up - since they are actually written to disk.

Using Dynamically Added Layers

The alternative is quite simple: Write a subclass of MultiFileSystem. Put it in the default lookup.

At runtime, when you want to add contents to the system filesystem, simply add additional filesystems to your MultiFileSystem. To remove the contents, simply remove those filesystems.

A convenient way to do this is to use XMLFileSystem - this is a filesystem created with exactly the same syntax as normal module XML layer files (see DevFaqModulesLayerFile). The following code loads an XML filesystem, which is in an XML file in the same package as the class, called dynamicContent.xml:

@ServiceProvider(service=FileSystem.class)
public class DynamicLayerContent extends MultiFileSystem {
    private static DynamicLayerContent INSTANCE;
    public DynamicLayerContent() {
        // will be created on startup, exactly once
        INSTANCE = this;
        setPropagateMasks(true); // permit *_hidden masks to be used
    }
    static boolean hasContent() {
        return INSTANCE.getDelegates().length > 0;
    }
    static void enable() {
        if (!hasContent()) {
            try {
                INSTANCE.setDelegates(new XMLFileSystem(
                        DynamicLayerContent.class.getResource(
                        "dynamicContent.xml")));
            } catch (SAXException ex) {
                Exceptions.printStackTrace(ex);
            }
        }
    }
    static void disable() {
        INSTANCE.setDelegates();
    }
}

In NetBeans 7.2 and later, the above code can be simplified by using Repository.LayerProvider. See its Javadoc for a usage example.

If finer grained control of what is added is needed at runtime, there are two possibilities, using this general approach:

• If the new layer contents are fixed and known, but perhaps correspond to user roles which may be overlaid together, split up the functionality for each role into a separate XML file (hint: define an enum of roles, where each role can point to an XML file URL, use EnumSet.of() and process that to decide what to enable)
• Write contents programmatically, but write folders/files to an in-memory filesystem created using FileUtil.createMemoryFileSystem() so the contents disappear on VM exit

https://bitbucket.org/jglick/dynamicmenudemo/ tries to automate this kind of task.

Sometimes you need to bundle some additional files with your module (for example native libraries or native executables).

Bundling External File With Your Module

NetBeans provides a simple and straightforward way to bundle whatever files you want into a module project:

• Create a folder in your project root directory called release/ (note this means the project root—the directory containing src/ and nbproject/ and MANIFEST.MF, not the source root directory of your module project!)
• Put anything you want bundled with your module in that directory or a subdirectory of release/
  • The entire subtree of this folder will be included in your cluster and bundled into your module's NBM file
  • Note that if what you are adding is a native library (DLL, .so file, etc.) there is a specific place to put this
• If the thing you are bundling can change (for example, you are bundling a library you wrote, and you may make changes to that library and recompile it), you may want to override your module's release-files to rebuild/re-copy that library (i.e. <target name="release" depends="compile-lib,projectized-common.release"/> and then create your own compile-lib target that rebuilds the library and copies it somewhere under release/ in your module project.

The result is:

• the files you are bundling are included in your module
  • Note that this does not mean they will be inside your module's JAR file (that would not be useful)
• They will be bundled with your module's JAR file and will be in a findable location at runtime (see below).

Note: If you are bundling third party software which has its own installer there is a way to run that installer during module installation.

Finding External Files At Runtime

Now your module includes the files you need. You still need to get access to them at runtime.

To do that, use InstalledFileLocator. That is a class which can find a file which was installed by a module. You simply give it your module's code-name (the thing you typed when you created the module, which looks like a package name) and a relative path (i.e. not including the release/ directory):

File emulator = InstalledFileLocator.getDefault().locate(
    "javacard/bin/jcre.exe",
    "org.netbeans.modules.javacard.referenceimpl",
    false);

Always handle the case that the user (or disk crash, whatever) might have deleted it.

If you are wondering why you don't just find the directory NetBeans is installed in and look in that directory, see the background information about clusters

The simplest way is to run New Action Wizard (File > New... > Module Development > Action) which creates an action for you and registers it in your layer.xml file.

See also:

• An example how to register action manually
• How do I add an action to a file of a given mime-type?
• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

The simplest way is to run New Action Wizard (File > New... > Module Development > Action) which creates an action for you and registers it in your layer.xml file.

See also:

• An example how to register action manually
• How do I add an action to a file of a given mime-type?
• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to my custom node?

There are several ways to do this, depending on what exactly you need. The basic problems all of the available solutions are addressing is that:

• An action may be created and shown in a menu, toolbar or popup menu.
• While it is visible on-screen, the selected file (or whatever) can change.
• If it is context sensitive, it should run against the thing it was shown for not whatever is selected at the millisecond when it is actually called
• People want to write main-menu and toolbar actions which are enabled and disabled based on what is selected - in practice this means writing an object that enables and disables itself based on a particular type — a particular class or its subclasses — being selected (each logical window in NetBeans has its own "selection"; the "global selection" is whatever is selected in whatever window currently has focus)

NetBeans allows context-sensitive actions to be registered declaratively using annotations.. In the IDE, File > New File > Module Development > Action will generate (on the first page of the wizard, specify that you want a context sensitive action):

 @ActionID(...)
 @ActionRegistration(...)
 @ActionReference(...)
 public final class SomeAction implements ActionListener {
   private final List<Project> context;
   public SomeAction(List<Project> context) {
     this.context = context;
   }
   public void actionPerformed(ActionEvent ev) {
     for (Project project : context) {
       // TODO use project
     }
   }
 }

which will be called if and only if one or more projects is selected. The good news is that the code is lightweight, simple and works; the bad news is that it doesn't handle more complicated enablement logic.

If you want to add this action into a context menu of a node you have to overwrite the getActions() method as follows:

 public Action[] getActions(boolean context) {
        List<? extends Action> myActions =
                Utilities.actionsForPath("Actions/YOUR_FOLDER");
        return myActions.toArray(new Action[myActions.size()]);
    }

If you need something more featureful, there are a few options, old and new:

NodeAction

NodeAction is somewhat more flexible, but requires more code to implement. It is just passed the array of activated nodes whenever that changes, and can choose to enable or disable itself as it wishes. Essentially this is just an action that automagically tracks the global Node selection.

Roll your own

The following is relatively simple and affords a way to perform whatever enablement logic you like (NodeAction can do that too, but this might be a little more straightforward and your code doesn't have to worry about nodes at all: DevFaqWhatIsANode). To understand how this works, see DevFaqTrackGlobalSelection:

public class FooAction extends AbstractAction implements LookupListener, ContextAwareAction {
    private Lookup context;
    Lookup.Result<Whatever> lkpInfo;
 
    public FooAction() {
        this(Utilities.actionsGlobalContext());
    }
 
    private FooAction(Lookup context) {
        putValue(Action.NAME, NbBundle.getMessage(FooAction.class, "LBL_Action"));
        this.context = context;
    }
 
    void init() {
        assert SwingUtilities.isEventDispatchThread() 
               : "this shall be called just from AWT thread";
 
        if (lkpInfo != null) {
            return;
        }
 
        //The thing we want to listen for the presence or absence of
        //on the global selection
        lkpInfo = context.lookupResult(Whatever.class);
        lkpInfo.addLookupListener(this);
        resultChanged(null);
    }
 
    public boolean isEnabled() {
        init();
        return super.isEnabled();
    }
 
    public void actionPerformed(ActionEvent e) {
        init();
        for (Whatever instance : lkpInfo.allInstances()) {
            // use it somehow...
        }
    }
 
    public void resultChanged(LookupEvent ev) {
        setEnabled(!lkpInfo.allInstances().isEmpty());
    }
 
    public Action createContextAwareInstance(Lookup context) {
        return new FooAction(context);
    }
}

Deprecated CookieAction

In many older (pre-NB 6.8) examples you may find CookieAction. It should be (but is not) deprecated. The original info is left here for reference and/or old code maintenance:

CookieAction is used to write actions that are sensitive to what is in the selected Node(s) Lookup. You can specify one or more classes that must be present in the selected Node's Lookup, and some other semantics about enablement.

Being an older class, under the hood it is using Node.getCookie(), so your action will only be sensitive to things actually returned by that method - in other words, only objects that implement the marker interface Node.Cookie can work here.

Not-Yet-Official spi.actions

This module is part of the platform as of 6.8, but has not yet become official API (and nobody seems to be willing to make it stable API, so judge your own decisions based on this fact). Nonetheless it is there, it is not changing and straightforward to use. The example below opens a visual editor window if an instance of RAFDataObject is selected and has a RandomAccessFile in its lookup:

public final class CustomOpenAction extends org.netbeans.spi.actions.Single<RAFDataObject>
 {
    public CustomOpenAction() {
      super(RAFDataObject.class, "Open", null);
    }
    @Override
    protected void actionPerformed(RAFDataObject target) {
      //If an editor is already open, just give it focus
      for (TopComponent tc : TopComponent.getRegistry().getOpened()) {
        if (tc instanceof RAFEditor && tc.getLookup().lookup(RAFDataObject.class) == target) {
          tc.requestActive();
          return;
        }
      }
      //Nope, need a new editor
      TopComponent editorWindow = null;
      editorWindow = new RAFEditor(target);
      editorWindow.open();
      editorWindow.requestActive();
    }
    @Override
    protected boolean isEnabled(RAFDataObject target) {
      //Make sure there really is a file on disk
      return target.getLookup().lookup(RandomAccessFile.class) != null;
    }
  }

Use ContextAction instead of Single to create actions that operate on multi-selections.

See org-openide-awt/org.openide.awt.Actions.checkbox(...)

Here an example for a checkable action which represents the state of the "ignoreCase" property within the property file "org/netbeans/modules/diff.properties"

   <folder name="Actions">
       <folder name="Diff">
           <file name="toggle-ignore-case-diff-option.instance">
               <attr bundlevalue="org.netbeans.modules.diff.Bundle#CTL_IgnoreCaseOptionAction" name="displayName"/>
               <attr name="Name" stringvalue="toggle-ignore-case-diff-option"/>
               <attr name="preferencesNode" stringvalue="/org/netbeans/modules/diff" />
               <attr name="preferencesKey" stringvalue="ignoreCase"/>
               <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.checkbox"/>
           </file>
       </folder>
   </folder>

When you use @ActionRegistration the META-INF/generated-layer.xml may contain:

<folder name="Actions">
   <folder name="Build">
     <file name="com-foo-SomeAction.instance"/>
   </folder>
</folder>
<folder name="Menu">
   <folder name="Build">
     <file name="pointerToComFooSomeAction.shadow">
        <attr name="originalFile" stringvalue="Actions/Build/com-foo-SomeAction.instance"/>
     </file>
   </folder>
</folder>

And you may have noticed that actions are usually put, not directly into the Menu/ folders, but into subfolders of this Actions/ folder. Then we create .shadow files that act like symbolic links, pointing to the real .instance file . Why all this indirection?

Older versions of the NetBeans UI included the ability to rearrange, and even delete, whole menus or individual menu items, and future ones may again. (Many applications built on NetBeans will not want to expose such customizability, but some do.) The current UI does include a key binding editor; the Actions/ folder can be used from this editor to list available actions, even those which are not currently bound to any keystroke.

Additionally, for actions which are javax.swing.Action but not SystemAction, creating the action instance in only a single place ensures that it acts as a singleton. (While the action class likely has no declared instance fields, it does have some state, notably information about keyboard accelerators which should be displayed in menu presenters.)

Applies to: NetBeans 6.7 and above

The simplest way is to run File > New... > Module Development > Action which creates an action for you and registers it in your layer.xml.

1. On the first tab, choose Conditionally Enabled action and select DataObject as the cookie class.
2. On the second tab, check File Type Context Menu Item and choose the MIME type and position.

You can use text/html, text/x-java, text/x-ant+xml, text/x-jsp, image/png, etc.

See also:

• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

The simplest way is to run New Action Wizard (File > New... > Module Development > Action) which creates an action for you and registers it in your layer.xml.

1. On the first tab, choose Conditionally Enabled action and select EditorCookie as the cookie class.
2. On the second tab, check Editor Context Menu Item and choose MIME type (text/x-java in this case) and position.

You can also use path="Editors/Popup" to add an action to all editor kits.

See also:

• How do I add an action to a file of a given mime-type?
• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

Just use @ActionReference(path="Projects/Actions"). The action should take a context parameter in its constructor.

See also How do I add an action to a project popup menu of a specific project type?

You can install an action into the context menu of all projects simply by adding to your layer under the folder Projects/Actions/. Your action should be context-sensitive, meaning it should be a placeholder which implements ContextAwareAction; the context-aware derived action will do the real work. Generally it will look for an instance of Project in the supplied Lookup (context).

If you just override isEnabled on the derived action based on the context, the menu item will always be present, though it will be greyed out in the case of inappropriate projects. If you want to hide the menu item for all but relevant projects, you need to set an additional flag (available starting in 6.9).

The following trivial action shows the location of a project so long as its name comes in the first half of the alphabet:

@ActionID(...)
@ActionRegistration(...)
@ActionReference(path="Projects/Actions")
public class DemoAction extends AbstractAction implements ContextAwareAction {
    public @Override void actionPerformed(ActionEvent e) {assert false;}
    public @Override Action createContextAwareInstance(Lookup context) {
        return new ContextAction(context);
    }
    private static final class ContextAction extends AbstractAction {
        private final Project p;
        public ContextAction(Lookup context) {
            p = context.lookup(Project.class);
            String name = ProjectUtils.getInformation(p).getDisplayName();
            // TODO state for which projects action should be enabled
            char c = name.charAt(0);
            setEnabled(c >= 'A' && c <= 'M');
            putValue(DynamicMenuContent.HIDE_WHEN_DISABLED, true);
            // TODO menu item label with optional mnemonics
            putValue(NAME, "&Info on " + name);
        }
        public @Override void actionPerformed(ActionEvent e) {
            // TODO what to do when run
            String msg = "Project location: "
                    + FileUtil.getFileDisplayName(p.getProjectDirectory());
            DialogDisplayer.getDefault().notify(new NotifyDescriptor.Message(msg));
        }
    }
}

Certain project types also read their context menu actions from type-specific folders.

Applies to: NetBeans 7.0+

• To add the Copy/Delete/Move/Rename action to your project's node, you should:

1. 1. Implement the corresponding interface such as org.netbeans.spi.project.CopyOperationImplementation.
   2. Implement org.netbeans.spi.project.ActionProvider:

public final class AddActionActions implements ActionProvider {
    private final AddActionProject project; //suppose this is your project
    public AddActionActions(AddActionProject project) {
        this.project = project;
    }
    public String[] getSupportedActions() {
        return new String[] {
            ActionProvider.COMMAND_COPY
        };
    }
    public boolean isActionEnabled(String command, Lookup context) {
        if (command.equals(ActionProvider.COMMAND_COPY)) {
            return true;
        } else {
            throw new IllegalArgumentException(command);
        }
    }
    public void invokeAction(String command, Lookup context) {
        if (command.equalsIgnoreCase(ActionProvider.COMMAND_COPY)){
            DefaultProjectOperations.performDefaultCopyOperation(project);
        }
    }
}

1. 1. Add these implementations to your project's lookup:

lookup = Lookups.fixed(
    // ... as before
    new AddActionOperation(this),
    new AddActionActions(this),
);

1. 1. Register the actions into the project node's context menu:

public @Override Action[] getActions(boolean context) {   
    Action[[ | ]] nodeActions = new Action[2];
    nodeActions[0] = CommonProjectActions.copyProjectAction();
    nodeActions[1] = CommonProjectActions.closeProjectAction();
    return nodeActions;
}

• To add the other actions specified in the Project API such as closeProjectAction, just add it to the list of actions of your node.
• To add an action you created yourself, just add it to the list of actions of your node.

See also: Common Project Actions

Use @ActionReference.

See also:

• How do I add an action to a file of a given mime-type?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

Override the public Action[[ | ]] getActions(boolean context) method of your node (99% of the time you can ignore the boolean parameter).

If this node is really a DataNode for your own file type, instead see DevFaqActionAddFileMime.

See also:

• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to the NetBeans tool bar?

• Override getActions() of your Node subclass.
• Create a custom subclass of javax.swing.Action which implements the interface Presenter.Popup.
• Return a JMenu with whatever you want on it from getPopupPresenter().
• Return that action in the array of actions from getActions().

@ActionReference(path="Editors/TabActions")

Applies to: NetBeans IDE 7.1 and above Platforms: All

To add a drop-down menu to a component in a toolbar, you can either extend CallableSystemAction and override public Component getToolbarPresenter(), or implement javax.swing.Action or any subclass thereof, and implement Presenter.Toolbar which defines that method.

You might want to create a JToggleButton, and when the button is pressed, show a JPopupMenu. (Also try org.openide.awt.DropDownButtonFactory.)

Example:

public class PickDrawingLineAction extends CallableSystemAction {
    private static JToggleButton toggleButton;
    private static ButtonGroup buttonGroup;
    private static JPopupMenu popup;
    private MyMenuItemListener menuItemListener;
 
    List handledCharts;
 
    public void performAction() {
        java.awt.EventQueue.invokeLater(new Runnable() {
            public void run() {
                toggleButton.setSelected(true);
            }
        });
 
    }
 
    public String getName() {
        return "Pick Drawing Line";
    }
 
    public HelpCtx getHelpCtx() {
        return HelpCtx.DEFAULT_HELP;
    }
 
    protected boolean asynchronous() {
        return false;
    }
 
    public Component getToolbarPresenter() {
        Image iconImage = Utilities.loadImage(
            "org/blogtrader/platform/core/netbeans/resources/drawingLine.png");
        ImageIcon icon = new ImageIcon(iconImage);
 
        toggleButton = new JToggleButton();
 
        toggleButton.setIcon(icon);
        toggleButton.setToolTipText("Pick Drawing Line");
 
        popup = new JPopupMenu();
        menuItemListener = new MyMenuItemListener();
 
        handledCharts = PersistenceManager.getDefalut()
                        .getAllAvailableHandledChart();
 
        buttonGroup = new ButtonGroup();
 
        for (AbstractHandledChart handledChart : handledCharts) {
            JRadioButtonMenuItem item =
                new JRadioButtonMenuItem(handledChart.toString());
            item.addActionListener(menuItemListener);
            buttonGroup.add(item);
            popup.add(item);
        }
 
        toggleButton.addItemListener(new ItemListener() {
            public void itemStateChanged(ItemEvent e) {
                int state = e.getStateChange();
                if (state == ItemEvent.SELECTED) {
                    /** show popup menu on toggleButton at position: (0, height) */
                    popup.show(toggleButton, 0, toggleButton.getHeight());
                }
            }
        });
 
        popup.addPopupMenuListener(new PopupMenuListener() {
            public void popupMenuCanceled(PopupMenuEvent e) {
                toggleButton.setSelected(false);
            }
            public void popupMenuWillBecomeInvisible(PopupMenuEvent e) {
                toggleButton.setSelected(false);
            }
            public void popupMenuWillBecomeVisible(PopupMenuEvent e) {
            }
        });
 
        return toggleButton;
    }
 
    private class MyMenuItemListener implements ActionListener {
        public void actionPerformed(ActionEvent ev) {
            JMenuItem item = (JMenuItem)ev.getSource();
            String selectedStr = item.getText();
 
            AnalysisChartTopComponent analysisTc =
                AnalysisChartTopComponent.getSelected();
 
            if (analysisTc == null) {
                return;
            }
 
            AbstractChartViewContainer viewContainer =
                analysisTc.getSelectedViewContainer();
            AbstractChartView masterView = viewContainer.getMasterView();
            if (!(masterView instanceof WithDrawingPart)) {
                return;
            }
 
            DrawingPart drawingPart =
                ((WithDrawingPart)masterView).getCurrentDrawing();
 
            if (drawingPart == null) {
                JOptionPane.showMessageDialog(
                        WindowManager.getDefault().getMainWindow(),
                        "Please add a layer firstly to pick line type",
                        "Pick line type",
                        JOptionPane.OK_OPTION,
                        null);
                return;
            }
 
            AbstractHandledChart selectedHandledChart = null;
 
            for (AbstractHandledChart handledChart : handledCharts) {
                if (handledChart.toString().equalsIgnoreCase(selectedStr)) {
                    selectedHandledChart = handledChart;
                    break;
                }
            }
 
            if (selectedHandledChart == null) {
                return;
            }
 
            AbstractHandledChart handledChart =
                selectedHandledChart.createNewInstance();
            handledChart.setPart(drawingPart);
            drawingPart.setHandledChart(handledChart);
 
            Series masterSeries = viewContainer.getMasterSeries();
            DrawingDescriptor description =
                viewContainer.getDescriptors().findDrawingDescriptor(
                    drawingPart.getLayerName(),
                    masterSeries.getUnit(),
                    masterSeries.getNUnits());
 
            if (description != null) {
                Node stockNode = analysisTc.getActivatedNodes()[0];
                Node node =
                    stockNode.getChildren()
                        .findChild(DescriptorGroupNode.DRAWINGS)
                        .getChildren().findChild(description.getDisplayName());
 
                if (node != null) {
                    ViewAction action =
                        (ViewAction)node.getLookup().lookup(ViewAction.class);
                    assert action != null :
                        "view action of this layer's node is null!";
                    action.view();
                }
            } else {
                /** best effort, should not happen */
                viewContainer.setCursorCrossVisible(false);
                drawingPart.setActived(true);
 
                SwitchHideShowDrawingLineAction.updateToolbar(viewContainer);
            }
 
        }
    }
 
}

Create an Action as described in the general FAQ for to add a dropdown menu to a toolbar.

In this case, your action also needs to implement ContextAwareAction. A ContextAwareAction is a factory for other Action instances which are tied to a specific Lookup (so that, if selection changes after the popup menu for a Node is shown, the Action does not operate on the wrong object). You can start with a subclass of javax.swing.AbstractAction, and you will need two constructors:

private final Lookup lookup;
public MyAction() {
  this (Utilities.actionsGlobalContext());
}
 
private MyAction(Lookup lookup) {
  this.lookup = lookup;
  Icon icon = ImageUtilities.image2Icon(
    ImageUtilities.loadImage("com/foo/icon.gif"));
  putValue(SMALL_ICON, icon);
  //set the initial enabled state
  setEnabled(false);
}

You will also need to implement the one method of ContextAwareAction:

public Action createContextAwareInstance(Lookup actionContext) {
  return new MyAction(actionContext);
}

To enable and disable the action, we will need to listen on the lookup for the presence or absence of some object type. If it is there, the action will be enabled; if it is not, it will be disabled.

Since we do not want to start listening on the global selection context until something actually cares whether the action is enabled or not, so we will override add/removePropertyChangeListener() to notice that and listen or not.

First, we must modify our class signature to implement LookupListener:

public class MyAction extends AbstractAction implements ContextAwareAction, LookupListener, Presenter.Toolbar {
...

Now we will handle listening on the Lookup.Result. We want to stop listening to it when there are no PropertyChangeListeners left, so that our action can be garbage collected if not in use:

private LookupResult<? extends DataObject> res;
 
@Override
public synchronized void addPropertyChangeListener(PropertyChangeListener l) {
  boolean startListening = getPropertyChangeListeners().length == 0;
  super.addPropertyChangeListener(l);
  if (startListening) {
    res = lookup.lookupResult(MyType.class);
    res.addLookupListener(this);
  }
}
 
@Override
public synchronized void removePropertyChangeListener(PropertyChangeListener l) {
  super.removePropertyChangeListener(l);
  if (getPropertyChangeListeners().length == 0) {
    res.removeLookupListener(this);
    res = null;
  }
}

Now comes the actual implementation of LookupListener:

public void resultChanged(LookupEvent ev) {
  setEnabled(!res.allItems().isEmpty());
}

A bit of bookkeeping is required in getToolbarPresenter() - at least until issue 179814 is fixed, we will need to manually enable/disable the actions for our menu items:

  private final Set<Action> popupMenuActions = new WeakSet<Action>();
  @Override
  public Component getToolbarPresenter() {
    JPopupMenu menu = new JPopupMenu();
    Action actionOne = new DemoMenuAction("One");
    Action actionTwo = new DemoMenuAction("Two");
    menu.add(new JMenuItem(actionOne));
    menu.add(new JMenuItem(actionTwo));
    popupMenuActions.add(actionOne);
    popupMenuActions.add(actionTwo);
    //add action listeners to the menu items to do what you want
    Icon icon = (Icon) getValue(SMALL_ICON);
    JButton result = DropDownButtonFactory.createDropDownButton(icon, menu);
    result.setAction(this);
    return result;
  }
 
  @Override
  public void setEnabled(boolean enabled) {
    super.setEnabled(enabled);
    for (Action a : popupMenuActions) {
      if (a != null) { //WeakSet iterator can return null
        a.setEnabled(enabled);
      }
    }
  }
 
  private class DemoMenuAction extends AbstractAction {
    DemoMenuAction(String name) {
      putValue(NAME, name);
      setEnabled (MyAction.this.isEnabled());
    }
 
    @Override
    public void actionPerformed(ActionEvent e) {
      DataObject ob = res.allInstances().iterator().next();
      DialogDisplayer.getDefault().notify(new NotifyDescriptor.Message(
              ob.getName()));
    }
  }

If we want the drop-down button to do something when it is clicked on the right side (not in the popup area with the down-arrow), we can implement actionPerformed(ActionEvent) to do whatever that is.

For an older detailed example of manually creating a context-aware drop-down toolbar button (without DropDownButtonFactory, circa NetBeans 6.0), see see this post, posted in on the old dev@openide NetBeans mailing lists.

To hide/show a toolbar dynamically in the NetBeans Platform, you should predefine a toolbar configuration first, then activate it.

1. Define toolbar configuration files alongside the module's layer: Standard.xml:

<?xml version="1.0"?>
<!DOCTYPE Configuration PUBLIC "-//NetBeans IDE//DTD toolbar//EN"
 "http://www.netbeans.org/dtds/toolbar.dtd">
<Configuration>
    <Row>
        <Toolbar name="View" />
        <Toolbar name="Control" />
        <Toolbar name="Indicator" />
        <Toolbar name="Draw" />
        <Toolbar name="Memory" />
    </Row>
    <Row>
        <Toolbar name="File" position="2" visible="false" />
        <Toolbar name="Edit" position="2" visible="false" />
        <Toolbar name="Build" position="2" visible="false" />
        <Toolbar name="Debug" position="2" visible="false" />
        <Toolbar name="Versioning" position="2" visible="false" />
    </Row>
</Configuration>

Developing.xml:

<?xml version="1.0"?>
<!DOCTYPE Configuration PUBLIC "-//NetBeans IDE//DTD toolbar//EN"
"http://www.netbeans.org/dtds/toolbar.dtd">
<Configuration>
    <Row>
        <Toolbar name="View" />
        <Toolbar name="Control" />
        <Toolbar name="Indicator" />
        <Toolbar name="Draw" />
        <Toolbar name="Memory" />
    </Row>
    <Row>
        <Toolbar name="File" position="2" />
        <Toolbar name="Edit" position="2" />
        <Toolbar name="Build" position="2" />
        <Toolbar name="Debug" position="2" visible="false" />
        <Toolbar name="Versioning" position="2" visible="false" />
    </Row>
</Configuration>

2. Register the configuration files in layer.xml:

<?xml version="1.0"?>
<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.0//EN"
 "http://www.netbeans.org/dtds/filesystem-1_0.dtd">
<filesystem>
    <folder name="Toolbars">
        <file name="Standard.xml" url="Standard.xml"/>
        <file name="Developing.xml" url="Developing.xml"/>
    </folder>
</filesystem>

3. At runtime, set the toolbar configuration that you want:

ToolbarPool.getDefault().setConfiguration("Developing");

If you are creating a custom application (e.g. Standalone Application in suite project properties) you specify a branding for the application. You can then override localized text strings from platform modules without modifying those modules directly; the overrides will be active whenever your branding is selected (this part is taken care of for you by the suite build harness). You will need to locate the module which defines the menu item and find the localized Bundle.properties which gives a label for it. Then you can create a file in your suite project like

branding/modules/jarname.jar/path/Bundle.properties

containing definitions of overridden labels.

When you enable branding on a suite the IDE automatically brands a few bundle strings for the main window title and so on, so you can look at these files for examples.

The Branding menu item on a suite (or Maven app project) lets you search for other strings and override them easily.

See also Technical details

Applies to: NetBeans 5.0, 5.5, 6.x

• Create your action and let it implement Presenter.Menu
• Return a special JMenuItem subclass that implements DynamicMenuContent from getMenuPresenter()
• Implement DynamicMenuContent methods to return the desired menu content, using TopComponent.Registry for finding the selected file in the editor.

https://bitbucket.org/jglick/dynamicmenudemo/ also does something similar.

Can I hide or show a whole menu or toolbar?

To hide a menu or toolbar you have to edit your layer.xml and append _hidden to the name of the desired menu or toolbar. You may also hide *.instance files.

It's generally much easier to do this from the NetBeans IDE, as described here.

Note that to hide the Navigate menu one has to declare GoTo_hidden instead of Navigate_hidden (the menu was originally named GoTo, but was later renamed to Navigate by the means of Bundle.properties).

Yes, any place where the APIs expect to have an item installed into a context or main menu, you can provide a submenu instead.

Provide a dummy Action (it can be a do-nothing subclass of javax.swing.AbstractAction), or in some cases the class need not even be an Action at all. For context menus, implement the interface Presenter.Popup on your Action, and have it return a JMenu from getPopupPresenter().

Similarly, you can implement other subinterfaces of Presenter to provide a different component to display in toolbars or the main menu.

Note about using alternate components in the main menu: If you want your action to work properly on Mac OS, you probably don't want to return anything other than a JMenu or JMenuItem from getMenuPresenter() if you implement Presenter.Menu. In general, Swing allows you to treat menu popups as generic Swing containers you can put what you like into. This is not true at all of the Mac OS screen menu bar - it expects normal menu items, and will not handle unusual contents for menus.

If you just return a JMenu from getPopupPresenter or getMenuPresenter it will always be displayed, though you can conditionally disable it. If you wish to sometimes hide (not just disable) the submenu, make it implement DynamicMenuContent and you can make the submenu appear or disappear whenever you like (or even provide more than one menu item / submenu).

When you click the close button in the top right corner the application closes. If you want to do something before the application closes (e.g. show a dialog with OK and Cancel options) or prevent it from closing, this is possible.

Make a class in your module that extends org.openide.modules.ModuleInstall. There is a Module Installer template that will create this class for you.

Override the closing method and insert your special logic. If you return false the application will not exit.

The Open File menu item is a part of the User Utilities module, in the ide cluster. This module can be added to your project using the Libraries page of the module property sheet. It must be also added to the suite (your suite > Project properties, Libraries > ide > User Utilities)

The User Utilities module also adds the Find in Files feature and support for PDF files (they are recognized and can be opened by double-clicking on them).

Looking at text in IDE such as a menu item, window title, node display name, etc. you may want to change it. But first you need to find where in the code this string is produced. It is very easy to find if you add the following switch into your .../etc/netbeans.conf:

-J-Dorg.openide.util.NbBundle.DEBUG=true

If you use this switch all strings loaded from Bundle.properties files using org.openide.util.NbBundle will have two numbers appended to them. The first number identifies the bundle file. Look for this number in the IDE log to find the location of the properties file that provides this string.

Another handy trick: in a built source tree, run

ant index-layer-paths

to see which module (by code name) contributes each layer file (or folder), including menu items and so on. You can also just look at the trunk version of this file here.

It's easy to add a separator to the menus by editing the module's layer file; in fact, the Action wizard will do this for you. Items in the main toolbar are also configured through the layer file, but you may find that adding a separator as you would for the menu does not work in the toolbar. So how do you add a separator to the toolbar?

You can do this by creating a class like:

package com.example.util.widgets;
 
public class VerticalSeparator extends JSeparator {
 
    public VerticalSeparator() {
        super(JSeparator.VERTICAL);
    }
 
    @Override
    public Dimension getMaximumSize() {
        return new Dimension(getPreferredSize().width, super.getMaximumSize().height);
    }
 
    @Override
    public Dimension getSize() {
        return new Dimension(getPreferredSize().width, super.getSize().height);
    }
}

Then simply reference an instance of this separator in the layer file:

<file name="SeparatorAfterModelToolbarActions.instance">
    <attr name="instanceClass" stringvalue="com.example.util.widgets.VerticalSeparator"/>
    <attr name="position" intvalue="25"/>
</file>

• If you want to remove the action from a toolbar, then remove entries like:

<folder name="Toolbars">
    <folder name="Build">
        <file name="org-nvarun-tat-SayCheez.shadow">
            <attr name="originalFile"
                  stringvalue="Actions/Tools/org-nvarun-tat-SayCheez.instance"/>
            <attr name="position" intvalue="325"/>
        </file>
    </folder>
</folder>

• If you want to remove either one of the separators, or even both of them, then delete the entries looking like:

<file name="org-nvarun-tat-separatorAfter.instance">
    <attr name="instanceClass" stringvalue="javax.swing.JSeparator"/>
    <attr name="position" intvalue="175"/>
</file>
<file name="org-nvarun-tat-separatorBefore.instance">
    <attr name="instanceClass" stringvalue="javax.swing.JSeparator"/>
    <attr name="position" intvalue="125"/>
</file>

• If you want to remove the action from a menu, and retain it only on the toolbar, then remove entries like:

<folder name="Menu">
    <folder name="Tools">
        <file name="org-nvarun-tat-SayCheez.shadow">
            <attr name="originalFile"
                  stringvalue="Actions/Tools/org-nvarun-tat-SayCheez.instance"/>
            <attr name="position" intvalue="150"/>
        </file>
        <file name="org-nvarun-tat-separatorAfter.instance">
            <attr name="instanceClass" stringvalue="javax.swing.JSeparator"/>
            <attr name="position" intvalue="175"/>
        </file>
        <file name="org-nvarun-tat-separatorBefore.instance">
            <attr name="instanceClass" stringvalue="javax.swing.JSeparator"/>
            <attr name="position" intvalue="125"/>
        </file>
    </folder>
</folder>

• If you want to remove an item from a module over which you have no control, such as a NetBeans Platform module, use the _hidden attribute:

<folder name="Toolbars">
    <folder name="Build">
        <file name="org-nvarun-tat-SayCheez_hidden"/>
    </folder>
</folder>

The New Action wizard allows you to uncheck both menu and toolbar placement for your action and only assign a keyboard shortcut. To learn how to do this manually, read on. Refer to TaT_HackingNetBeansXMLLayerPartOne for more details.

Trick #1

• Retain the action's basic registration:

<folder name="Actions">
    <folder name="Tools">        
        <file name="org-nvarun-tat-SayCheez.instance"/>
    </folder>
</folder>

• This registers an action as a Global Menu Item:

<folder name="Menu">
    <folder name="Tools">
        <file name="org-nvarun-tat-SayCheez.shadow">
            <attr name="originalFile"
                  stringvalue="Actions/Tools/org-nvarun-tat-SayCheez.instance"/>
            <attr name="position" intvalue="150"/>
        </file>
    </folder>
</folder>

• This registers an action as a Global Toolbar Button:

<folder name="Toolbars">
    <folder name="Build">
        <file name="org-nvarun-tat-SayCheez.shadow">
            <attr name="originalFile"
                  stringvalue="Actions/Tools/org-nvarun-tat-SayCheez.instance"/>
            <attr name="position" intvalue="325"/>
        </file>
    </folder>
</folder>

• To assign a shortcut key, replace either or both of them with something like the following:

<folder name="Shortcuts">
    <file name="O-F3.shadow">
        <attr name="originalFile"
              stringvalue="Actions/Tools/org-nvarun-tat-SayCheez.instance"/>
    </file>
</folder>

Trick #2

• In the above example the action has the shortcut key Alt+F3, which is represented as O-F3. In general, if you have some key combination that uses Alt (or the equivalent on Mac OS X), then use O. Separate modifiers from the base keycode name with -, and append .shadow for the filename. Ctrl (or its Mac equivalent) is represented by D, and Shiftby S. (C and A represent the literal Ctrl and Alt keys, but this is less portable.)

Tips to Remember

1. Following are some keycode equivalents. See Javadoc for KeyEvent for the full list:

• A to Z (as is), F1 to F12 (as is), 0 to 9 (as is)
• / as SLASH, \ as BACK_SLASH
• ; as SEMI_COLON
• . as PERIOD
• ‘ as QUOTE

See also DevFaqKeybindings.

(Reposted from this entry on NetBeans Zone.)

The main menus and toolbars of a NetBeans Platform application are configured based on the contents of folders in the system filesystem. There are many benefits of this approach, such as improved performance since the platform can create all the menus and toolbars without having to actually instantiate the actions with which they are associated.

Because the platform builds the menus and toolbars for you, it might seem like you have little control over how those items appear. In practice, you have a great deal of control over the appearance for any action you create. Typically, actions in a NetBeans platform application which will be shown in the main menu or toolbar extend from CallableSystemAction, perhaps indirectly through its CookieAction subclass.

In the code you've written for one of these actions, you can override getMenuPresenter to change the appearance of the menu item associated with your action and/or override getToolbarPresenter to change the appearance of the toolbar component associated with your action.

For example, if you wanted to make the menu item for your action have a blue background and yellow text, you could do something like this:

@Override
public JMenuItem getMenuPresenter() {
    JMenuItem item = super.getMenuPresenter();
    item.setOpaque(true);
    item.setBackground(Color.BLUE);
    item.setForeground(Color.YELLOW);
    return item;
}

Note that if you are changing the menu item to support a tooltip, the object returned by getMenuPresenter needs a property change listener on the action's SHORT_DESCRIPTION so that its tooltip value is updated correctly upon change.

Note about using alternate components in the main menu: If you want your action to work properly on Mac OS, you probably don't want to return anything other than a JMenu or JMenuItem from getMenuPresenter() if you implement Presenter.Menu. In general, Swing allows you to treat menu popups as generic Swing containers you can put what you like into. This is not true at all of the Mac OS screen menu bar - it expects normal menu items, and will not handle unusual contents for menus.

Problem: In a NetBeans Platform application, it is conceivable that the Output window's only use could be to show logging messages to the user. In this case, since the Output TopComponent is always persisted, and the IDE log is only attached via an Action, the Action should be invoked whenever the Output window is open.

Solution: We can create an Installer class which will search for the existence of the Output window, and conditionally fire the action which attaches the IDE Log.

Waiting for the Windows System to be ready

Installer classes (those that extend ModuleInstall) will fire their restored() methods before the Windows System is available. This is a problem, since we need to be able to interrogate the TopComponent.Registry to determine if the Output window is open.

The answer is to use the WindowManager.getDefault().invokeWhenUIReady() method.

    @Override
    public void restored()
    {
        //The TopComponent we're interested in isn't immediately available. 
        //This method allows us to delay start of our procedure until later.
        WindowManager.getDefault().invokeWhenUIReady(new Runnable()
        {
            @Override
            public void run()
            {
                 //Do something
            }
        });
    }

Finding the Output TopComponent

We find the Output TopComponent by the WindowManager.getDefault().findTopComponent() method. We must know the ID of the TopComponent we are searching for. In this case, it is "output".

            @Override
            public void run()
            {
                //Locate the Output Window instance                
                final String OUTPUT_ID = "output";
                TopComponent outputWindow = WindowManager.getDefault().findTopComponent(OUTPUT_ID);

Determining if the Output window is open

This is easily accomplished by using the methods of the TopComponent class.

               if (outputWindow != null && outputWindow.isOpened())

Locating our Action from the System Filesystem (Layer)

We can get a Lookup for a portion of the System Filesystem using Lookups.forPath(). Browse your layer file in context to determine where the instance of the action is stored. In our case, it is in Actions/View.

                   final String FOLDER = "Actions/View/";
                   Lookup pathLookup = Lookups.forPath(FOLDER);

Getting the Instance from our Lookup

Now that we have a lookup to the appropriate folder of the System Filesystem, we need to know the instance file name of the Action we want to retrieve and invoke. We get this information from browsing our layer file in context. In our case, it is "org-netbeans-core-actions-LogAction". We then invoke actionPerformed() to fire the action.

Action a = FileUtil.getConfigObject("Actions/org-netbeans-core-actions-LogAction.instance", Action.class);
if (a != null) {
    action.actionPerformed(null);
}

Putting it all together

Here is the completed Installer class, with logging.

/**
 * This class makes it so that the action View/IDE-Logs is performed upon startup
 * whenever the Output window is open.
 */
public class ViewLogsInstaller extends ModuleInstall
{
    private static final Logger logger = Logger.getLogger(ViewLogsInstaller.class.getName(), ViewLogsInstaller.class.getPackage().getName() + ".Log");

    @Override
    public void restored()
    {
        //The TopComponent we're interested in isn't immediately available. 
        //This method allows us to delay start of our procedure until later.
        WindowManager.getDefault().invokeWhenUIReady(new Runnable()
        {
            @Override
            public void run()
            {
                //Locate the Output Window instance                
                final String OUTPUT_ID = "output";
                logger.log(Level.FINE, "LOG_FindingWindow", OUTPUT_ID);
                TopComponent outputWindow = WindowManager.getDefault().findTopComponent(OUTPUT_ID);
                
                //Determine if it is opened
                if (outputWindow != null && outputWindow.isOpened())
                {
                    logger.log(Level.FINE, "LOG_WindowOpen", OUTPUT_ID);
                    final String FOLDER = "Actions/View/";
                    final String INSTANCE_FILE = "org-netbeans-core-actions-LogAction";

                    //Use Lookup to find the instance in the file system
                    logger.log(Level.FINE, "LOG_LookupAction", new Object[]{FOLDER, INSTANCE_FILE});
                    Lookup pathLookup = Lookups.forPath(FOLDER);
                    Template<Action> actionTemplate = new Template<Action>(Action.class, FOLDER + INSTANCE_FILE, null);
                    Result<Action> lookupResult = pathLookup.lookup(actionTemplate);
                    Collection<? extends Action> foundActions = lookupResult.allInstances();
                    
                    //For each instance (should ony be one) call actionPerformed()
                    for (Action action : foundActions)
                    {
                        logger.log(Level.FINE, "LOG_FoundAction", action);
                        action.actionPerformed(null);
                    } 
                }
                else
                {
                    logger.log(Level.FINE, "LOG_WindowClosed", OUTPUT_ID);
                }
            }
        });
    }
}

Log.properties file

Place this file in the root package of your installer.

LOG_FindingWindow=Attempting to locate TopComponent with ID ''{0}''
LOG_WindowOpen=TopComponent with ID ''{0}'' is open
LOG_LookupAction=Attempting to find Action instance at {0}{1}
LOG_FoundAction=Found Action ''{0}''; calling actionPerformed()
LOG_WindowClosed=TopComponent with ID ''{0}'' is closed or not instantiated

The NetBeans Platform provides the ability to enable and disable Actions based upon what is selected in the current logical window--this is known as the "global selection". In this article I show how to extend this selection concept to include objects that are global to the entire application. Using this technique, you'll be able to leverage existing idioms for creating context-sensitive actions and querying the global selection, but the scope of your operations will be expanded from the context of the current window to the context of the entire application. That's a pretty powerful extension point that demonstrates the strength and versatility of the NetBeans Platform APIs.

This FAQ will add a Project instance to the global selection. However, you could add any object, for instance a NavigatorHint, or perhaps you could keep track of the last used "widget".

Use Cases

Consider the following use cases. Each one interacts with the global selection in some way. Each one would benefit by giving the currently selected project an application-wide scope.

Use Case #1

You want to create a context sensitive action that is enabled when a project is selected in the Projects window, and that remains enabled when the focus changes to another window. For example:

@ActionID(...)
@ActionRegistration(...)
@ActionReference(...)
public final class CloseProjectAction implements ActionListener
{
    private final Project project;
 
    public CloseProjectAction(Project context)
    {
        this.project = context;
    }
 
    @Override
    public void actionPerformed(ActionEvent e)
    {
        OpenProjects.getDefault().close(new Project[] { project });
    }
}

Use Case #2

You want an Action to interact with a capability found in the current project. Your Action is in a loosely coupled module that knows nothing about projects other than the NetBeans Project API and your capability's API. For example:

@ActionID(...)
@ActionRegistration(...)
@ActionReference(...)
public final class SomeAction implements ActionListener
{
    @Override
    public void actionPerformed(ActionEvent event)
    {
        Project project = Utilities.actionsGlobalContext().lookup(Project.class);
        if (project != null)
        {            
            SomeCapability capability = project.getLookup().lookup(SomeCapability.class);
            if (capability != null)
            {
                 ...
            }
            ...
        }
    }
}

Use Case #3

You want to update the main window title based on an attribute in the current project, for instance, the name. You want to use a simple LookupListener that listens for the selected projects in the global selection. For example:

/**
 * This class provides the application's window title with the selected 
 * project's name.
 */
public class MainWindowTitleManager
{
    private static Lookup.Result<Project> lookupResults;
    private static LookupListener lookupListener;
 
    /**
     * Creates a LookupListener on the Project.class that 
     * handles changes in the project selection.
     */
    public static void activate()
    {
        if (lookupResults == null)
        {
            // Monitor the existance of Projects in the global context lookup
            lookupResults = Utilities.actionsGlobalContext().lookupResult(Project.class);
            // Create the listener on the lookupResults
            lookupListener = new LookupListener()
            {
                // Update window title when the Project changes
                @Override
                public void resultChanged(LookupEvent ignored)
                {
                    String projectName;
                    Collection<? extends Project> projects = lookupResults.allInstances();
                    if (projects.isEmpty())
                    {
                        projectName = "<No Project>";
                    }
                    else if (projects.size() == 1)
                    {
                        Project project = projects.iterator().next();
                        projectName = ProjectUtils.getInformation(project).getDisplayName();
                    }
                    else
                    {
                        projectName = "Multiple Projects";
                    }
                    demonstrateUpdateWindowTitle(projectName);
                }
            };
            // Activate the listener
            lookupResults.addLookupListener(lookupListener);
            lookupListener.resultChanged(null);
        }
    }
 
    static void demonstrateUpdateWindowTitle(final String projectName)
    {
        // We have to do this on the AWT thread, so we use the invokeWhenUIReady
        // method which can be called from any thread.
        {
            WindowManager.getDefault().invokeWhenUIReady(new Runnable()
            {
                @Override
                public void run()
                {
                    Frame mainWindow = WindowManager.getDefault().getMainWindow();
                    mainWindow.setTitle(projectName);
                }
            });
        }
    }
}