Getting Started with the NetBeans Platform

Getting Started with the NetBeans Platform

By Tom Wheeler, OCI Senior Software Engineer

September 2005


When developers think of NetBeans, they typically think of the popular open-source IDE. I want to be clear from the beginning: this is not an article about how to use the IDE. Instead, I'll explain how to get a head start towards creating desktop applications by reusing the infrastructure on which the IDE itself is built. This will allow you to spend more time on the business logic and less time on the infrastructure development common to any GUI application. This article introduces the NetBeans platform and shows you how you can get started by reusing existing components. Next month, I'll follow up with another article that describes how to create a custom application using your own code.

You don't have to use the NetBeans IDE to benefit from the platform, in fact I generally use Eclipse. Ironically, the two most recent production versions of the NetBeans IDE don't even offer support for creating platform modules, though the latest development release does. By the end of this article you'll be able to use existing components to construct a file browser capable of copying, deleting and renaming files as well editing any text-based file. The browser will be able to display PNG, JPEG and GIF image files and you can use any IDE — or even none at all — to create it. This article describes how to create a simple application using version 4.1 of NetBeans platform. Version 5.0 of NetBeans IDE will include improved support for creating applications on the NetBeans platform.

Think about the last few desktop applications you've created. They probably had at least some facilities for window management, online help and file editing. More complex applications may have required a "plugin" architecture in which components could locate and use services provided by other components, an approach that can quickly become complex when you try manage compile-time and run-time dependencies between modules. Though each implementation is remarkably similar, these features are often rewritten from scratch for each project. Isn't code reuse supposed to be one of the ideals of object-oriented development?

A few years ago, the NetBeans developers realized that the IDE represented an incredibly sophisticated Java application (though arguably performance was lacking at the time, I assure you that it is now much improved). They saw that parts of it could be factored out into a "generic" desktop application that could be extended to create other applications, and the NetBeans Platform was born. A page on the NetBeans Web site lists a few applications that have been created on the platform, but the mailing lists show that many more people are using it to create applications for internal use.


The NetBeans platform represents an extremely minimal set of components from the IDE. Even though the compressed binary package is about four megabytes, it offers an impressive set of features:


I've explained several benefits of the NetBeans platform, but in order to give an accurate picture, I want to list some of the problems I've had:


Now that I've discussed the platform and its merits, I want to briefly define a few terms before we begin building our file browser application. Tim Boudreau's POV-Ray Tutorial covers many of the main classes and concepts, so I'll focus on the terms related to building an application on the NetBeans platform:

Required Tools

In order to create the file browser, you'll need to install the following tools:

Installing the Cluster Build Harness

The build harness is simply a set of files that help you to build modules into a cluster, plus two example modules to help get you started. To install it, you just unpack the cluster harness to some directory on your computer. I'll refer to the path of the directory it creates as CLUSTER_PATH, though you don't need to set an environment variable to point to it.

After unpacking the cluster harness, you should see the three subdirectories described below:

nbbuild this contains the core build scripts and properties files
snipe a module that shows a simple example of file type support
image a module that shows a more complex example of file type support

Testing the Installation

The cluster harness is already configured to include the snipe and image modules. The tryme target in the Ant script will build the modules and launch the platform with this cluster, so change to the nbbuild directory and issue the following command:

ant tryme

As I mentioned before, you'll have to agree to the licenses in order to unscramble the JARs. Afterwards, the platform should launch. If not, back up and retrace your steps.

You can verify that the modules are correctly installed by going to the Tools menu, selecting Options and then expanding the System -> Modules node. You should see a Samples section that lists the Snipe module when opened, and a Data Files section that contains the Image module. Also, if you expand the Object Types tree in the same section, you can see that loaders are configured for both snipe and image files, as shown in figure 1.

Figure 1: Screenshot of the options dialog after a successful cluster build

Screenshot of the options dialogue after a successful cluster build

The snipe module enables the NetBeans platform to recognize files with a .snipe extension. This gives a very simple example that you could extend to enable importing, viewing or other operations on the file formats you need to support in your application. The image module illustrates how to implement such a viewer.

If you examine the File menu, you'll see that there is no menu item for opening a file. As I wrote earlier, the NB platform represents the most basic components from the IDE sources, so we'll add a module that allows you to browse and open files.

The apisupport/cluster_harness/diskexplorer/ directory on the NetBeans CVS server contains a module called diskexplorer that displays a tree view of the local filesystem similar to the one built into many operating systems. I have modified this code slightly to add a build.xml file and to avoid calling the component from the AWT event dispatching thread. Again, I am contributing the changes back to the NetBeans project, but for now, you should download my modified version. Here are the steps to take to add it to the cluster:

1.    Unzip the diskexplorer module source to the CLUSTER_PATH directory. It should be parallel with the snipe and nbbuild directories. 

2.    Edit the nbbuild/ file and add diskexplorer to the list of modules in your cluster. Values in the module list are comma-delimited and backslashes are used to span lines. It should look like this when you're done:

cluster.mycluster1= snipe, \
                    image, \

3.     Edit nbbuild/modules.xml and add the diskexplorer section (blue text) after the snipe module element, as shown below:

  1. <module>
  2. <path>snipe</path>
  3. <cnb>org.netbeans.modules.snipe</cnb>
  4. </module>
  6. <module>
  7. <path>diskexplorer</path>
  8. <cnb>org.netbeans.modules.diskexplorer</cnb>
  9. </module>

The path element contains the directory name that contains this module, while the cnb element specifies the "code name base" that uniquely identifies the module. You don't need to add a section for the image module; since it's part of NetBeans it already has a listing in modules.xml file.

Before you can see how the platform treats .snipe files, you'll have to make one. Just create an empty text file named example.snipe somewhere on your system, and then run ant tryme to rebuild and start the cluster. You'll see some compiler warnings for the disk explorer module's calls to deprecated APIs, but they can safely be ignored.

Once the platform starts, click the View menu and choose the item named Disk Explorer. A new window should appear on the left side of the main frame. This section of the window is called the explorer mode. Browse to your example.snipe file using the disk explorer and you'll see that it has a special icon. You can open the file for viewing by double-clicking its icon. The default viewer for this type of file is the simplest possible — it just shows a larger version of the icon regardless of the file's contents, as shown here:

Figure 2: Screenshot of an opened snipe file

Screenshot of an opened snipe filed

The image module is a more complex example of a file viewer. It allows you to zoom in, zoom out and add gridlines on any supported image type. To see it in action, browse to a directory on your system that has an image file in GIF, JPEG or PNG format. You should see a special icon denoting it as an image file. Double-clicking it will display the image in the main part of the window, as shown in figure 3.

Figure 3: Screenshot of the displayed image file

Screenshot of the displayed image file

Now try opening a few more files, then close the platform and run ant tryme again. You should see that the windows you had open are retained after the platform starts. Finally, right-click (Ctrl + click for Mac OS X) on any file in the disk explorer and you'll see that the module provides support for cutting, copying, pasting, deleting and renaming any type of file. You can also open and edit any text file just by double-clicking on it.

For an even more sophisticated example of creating a new module to support a new file type, check out Tim Boudreau's tutorial in which he explains how to add support for POV-Ray scene files.

Now that you're able to build a simple application on the NetBeans platform, I encourage you to learn more by exploring some of the links I've provided in this article. Next month, I will conclude my discussion of the NetBeans platform by showing you how to build a stock trading simulation game from scratch.

Tom Wheeler would like to thank Rich Unger and Jeff Brown for their help in reviewing this article

Software Engineering Tech Trends (SETT) is a regular publication featuring emerging trends in software engineering.