NetBeans Platform 7.0:A Framework for Building Pluggable Enterprise Applications

By Heiko Böck, Anton Epple, Miloš Šilhánek, Andreas Stefik, Geertjan Wielenga, and Tom Wheeler

ABOUT NETBEANS PLATFORM

The NetBeans Platform is a generic framework for commercial and open-source desktop Swing applications.

It provides the “plumbing” (such as the code for managing windows, connecting actions to menu items, and updating applications at runtime) that you would otherwise need to write yourself. The NetBeans Platform provides all of these out of the box on top of a reliable, flexible, and well tested modular architecture.

In this refcard, you are introduced to the key concerns of the NetBeans Platform, so that you can save years of work when developing robust and extensible applications.

GETTING STARTED

To get started with the NetBeans Platform:

MAIN FEATURES

The following are the main features of the NetBeans Platform, showing you the benefits of using it rather than your homegrown Swing framework.

NETBEANS PLATFORM MODULES

The NetBeans Platform consists of a large set of modules. You do not need all of them. In fact, you only need six. None of these six provide any UI at all, meaning that you can create server or console applications on the NetBeans Platform since UI is not mandatory in any way at all.

Complete list of NetBeans Platform modules:

boot.jar
core.jar
org-openide-filesystems.jar
org-openide-modules.jar
org-openide-util.jar
org-openide-util-lookup.jar

org-netbeans-core.jar
org-netbeans-core-ui.jar

org-netbeans-core-netigso.jar
org-netbeans-core-osgi.jar
org-netbeans-libs-felix.jar
org-netbeans-libs-osgi.jar

org-netbeans-core-output2.jar
org-openide-io.jar
org-netbeans-core-io-ui.jar

org-netbeans-core-multiview.jar

org-openide-windows.jar
org-netbeans-core-windows.jar

org-netbeans-modules-autoupdateservices.
jar
org-netbeans-modules-autoupdate-ui.
jar

org-netbeans-modules-favorites.jar

org-openide-actions.jar

org-openide-loaders.jar

org-openide-nodes.jar
org-openide-explorer.jar

org-netbeans-modules-javahelp.jar

org-netbeans-modules-editormimelookup.
jar
org-netbeans-modules-editormimelookup-
impl.jar

org-netbeans-modules-masterfs.jar

org-netbeans-modules-options-api.jar

org-netbeans-api-progress.jar
org-netbeans-modules-progress-ui.jar
org-openide-execution.jar
org-netbeans-core-execution.jar

org-netbeans-modules-queries.jar

org-netbeans-modules-sendopts.jar

org-netbeans-modules-settings.jar

org-openide-awt.jar

org-openide-dialogs.jar

org-openide-text.jar

org-netbeans-api-visual.jar

org-netbeans-spi-quicksearch.jar

org-netbeans-swing-plaf.jar
org-netbeans-swing-tabcontrol.jar

NETBEANS PLATFORM APIs

The NetBeans Platform provides a large set of APIs. You do not need to know or use all of them, just those that make sense in your specific context. Below are the main API groupings, together with the most important information related to the grouping, such as their most important configuration attributes and API classes.

Module System

A module is a JAR file with special attributes in its manifest file. This is a typical NetBeans module manifest file:

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.1
Created-By: 11.3-b02 (Sun Microsystems Inc.)
OpenIDE-Module-Public-Packages: -
OpenIDE-Module-Module-Dependencies: org.openide.util > 7.31.1.1
OpenIDE-Module-Java-Dependencies: Java > 1.5
OpenIDE-Module-Implementation-Version: 091216
AutoUpdate-Show-In-Client: true
OpenIDE-Module: org.demo.hello
OpenIDE-Module-Layer: org/demo/hello/layer.xml
OpenIDE-Module-Localizing-Bundle: org/demo/hello/Bundle.properties
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Requires: org.openide.modules.ModuleFormat1

These are the most important NetBeans-related manifest attributes:

Window System

The window system handles the display of JPanel-like components and integrates them with the NetBeans Platform. The main classes are listed below.

A mode (that is, a window position) is defined in an XML file, which is contributed to the central registry via entries in the layer.xml file.

The NetBeans Platform provides a set of default modes, the most important of which are as follows:

TopComponents are registered in the system as follows:

@TopComponent.Description(preferredID = “DemoTopComponent”,
iconBase=”SET/PATH/TO/ICON/HERE”,
persistenceType = TopComponent.PERSISTENCE_ALWAYS)
@TopComponent.Registration(mode = “editor”, openAtStartup = true)
@TopComponent.OpenActionRegistration(displayName = “#CTL_DemoAction”,
preferredID = “DemoTopComponent”)
public final class DemoTopComponent extends TopComponent {
//
}

At compile time, the annotations above are converted to entries in a generated layer file, in the “build” folder.

For all the details, see: http://bits.netbeans.org/dev/javadoc/orgopenide- windows/org/openide/windows/doc-files/api.html

Lookup

Lookup is a data structure for loosely coupled communication. It is similar to but more powerful than the ServiceLoader class in JDK 6 (for example, Lookup supports event notifications). This enables you to load objects into the context of your application, but also into the context of NetBeans UI components, such as windows and nodes. These are the most important Lookups to be aware of:

These are typical tasks related to Lookup and how to code them:

MyServices = Lookup.getDefault().
lookup(MyService.class)

Collection<? extends MyService> coll = Lookup.
getDefault().lookupAll(MyService.class)

Lookup.Result lkpResult = theLookup.
lookupResult(MyObject.class);
lkpResult.addLookupListener(
 new LookupListener() {
	@Override
	public void resultChanged(LookupEvent e)(
		Result res = (Result) e.getSource();
		Collection<? extends MyObject>
		coll = res.allInstance();
		//iterate through the collection
	}
);

//Lookup for single object:
Lookup lkp = Lookups.singleton( myObject );

//Lookup for multiple objects:
Lookup lkp = Lookups.fixed(myObject, other);

//Lookup for dynamic content:
InstanceContent ic = new InstanceContent();
Lookup lkp = new AbstractLookup(ic);
ic.add(myObject);

Lookup commonlkp = new ProxyLookup(
dataObjectLookup, nodeLookup,
dynamicLookup);

 //In the constructor of TopComponent:
associateLookup(myLookup);

new AbstractNode(myKids, myLookup);
new BeanNode(myDomainObj, myKids, myLookup);
new DataNode(myDataObject, myKids,
myLookup);

Implement Lookup.Provider.

For all the details, see: http://wiki.netbeans.org/NetBeansDeveloperFAQ#Lookup</p>

Central Registry (System FileSystem)

The central registry is organized as a virtual file system accessible by all the modules in a NetBeans Platform application. NetBeans Platform APIs, such as the Window System API, make available extension points enabling you to declaratively register your components. A module’s contributions to the system are provided by specialized XML files, called “layer files”, normally named “layer.xml”.

Below are the most important extension points provided out of the box by the NetBeans APIs, represented by folders in a layer file:

Actions, Menu, Toolbars, OptionsDialog, Services, Shortcuts, TaskList,
and Windows2.

The NetBeans Platform helps you to register items correctly in the file system by letting you annotate your classes instead of requiring you to manually type XML tags in the layer.xml file by hand. The current list of annotations (in the NetBeans Platform, as well as NetBeans IDE) are listed below:

@ActionID, @ActionReference, @ActionReferences, @ActionRegistration,
@AntBasedProjectRegistration, @CompositeCategoryProvider.Registration,
@ConvertAsJavaBean, @ConvertAsProperties, @EditorActionRegistration,
@HelpSetRegistration, @LookupMerger.Registration,
@LookupProvider.Registration, @MimeLocation, @MimeRegistration,
@MimeRegistrations, @NbBundle.Messages, @NodeFactory.Registration,
@OptionsPanelController.ContainerRegistration,
@OptionsPanelController.SubRegistration,
@OptionsPanelController.TopLevelRegistration,
@ProjectServiceProvider, @ServiceProvider, @ServiceProviders,
@ServicesTabNodeRegistration, @TopComponent.OpenActionRegistration,
@TopComponent.Registration

The registry makes use of the FileSystem API to access the registered data.

FileSystem API

The FileSystem API provides stream-oriented access to flat and hierarchical structures, such as disk-based files on local or remote servers, memory-based files, and even XML documents.

Items within the folders in the layer.xml file are not java.io.Files, but org.openide.filesystems.FileObjects. The differences between them are as follows:

Converting between common data types:

FileUtil.toFile(FileObject fo)

FileUtil.toFileObject(File f)

DataObject.find (FileObject fo)

theDataObject.getPrimaryFile()

theDataObject.getNodeDelegate()

DataObject dob = n.getLookup().lookup
(DataObject.class);
if (dob != null) {
     //do something
}

//Get the root:
FileUtil.getConfigRoot()
//Get a specific folder:
FileUtil.getConfigFile(“path/to/my/
folder”)

The NetBeans Platform provides custom URLs:

For all the details, see: http://bits.netbeans.org/dev/javadoc/org-openide-filesystems

Actions

Actions are functions invoked when the user presses a menu item, toolbar button, or keyboard shortcut.

When porting your existing application to the NetBeans Platform, you do not need to change the code in your standard JDK actions (AbstractAction, ActionListener, etc).

Instead, you need to register them via class-level annotations which, when the module is compiled, will result in entries generated in the module’s layer file.

Below is shown how an action is registered:

@ActionID(category = “File”,
id = “org.demo.project.actions.DemoAction”)
@ActionRegistration(iconBase = “org/demo/resources/icon.png”,
displayName = “#CTL_DemoAction”)
@ActionReferences({
	@ActionReference(path = “Menu/File”, position = 0),
	@ActionReference(path = “Toolbars/File”, position = 0),
	@ActionReference(path = “Shortcuts”, name = “D-SPACE”)
})
@Messages(“CTL_DemoAction=Demo”)
	public final class DemoAction implements ActionListener {
	@Override
public void actionPerformed(ActionEvent e) {
		// TODO implement action body
	}
}

The entries generated into the layer file from the annotation above are used by the NetBeans Platform to construct the application’s actions, menus, toolbars, and keyboard shortcuts.

For all the details, see: http://bits.netbeans.org/dev/javadoc/org-openide-awt

When needing to change a component in the menu bar or toolbar, extend AbstractAction and implement Presenter:

@ActionID(category = “Build”, id = “org.demo.module1.DemoAction”)
@ActionRegistration(iconBase = “org/demo/module1/icon.png”,
displayName = “#CTL_DemoAction”)
@ActionReferences({
	@ActionReference(path = “Menu/File”, position = 0),
	@ActionReference(path = “Toolbars/File”, position = 0),
	@ActionReference(path = “Shortcuts”, name = “D-M”)
})
public final class DemoAction extends AbstractAction implements
Presenter.Toolbar
{
	public void actionPerformed(ActionEvent e) {
		// TODO implement action body
	}
	public Component getToolbarPresenter() {
		// TODO define the component to be displayed
	}
}

The Presenter class provides inner interfaces for creating customized presentation features for an Action. The following are available.

Nodes, Explorer Views, & Property Sheets

A Node is a generic model for a business object, which it visualizes within an Explorer View. Each Node can have visual attributes, such as a display name, icon, properties, and actions.

The list of Nodes is below, which you can use as is or extend as needed:

For all the details, see: http://bits.netbeans.org/dev/javadoc/orgopenide- nodes/org/openide/nodes/doc-files/api.html

A Node is a container for its own child nodes, created via a children class.

Less Used: Children.Array, Children.Map, and Children.SortedArray.

Explorer views are Swing components that display Node hierarchies.

Less Used: IconView, ListView, ChoiceView, ContextTreeView, MenuView, and TableView.

For all the details, see: http://bits.netbeans.org/dev/javadoc/orgopenide- explorer/org/openide/explorer/doc-files/api.html

The NetBeans Platform provides default property editors for:

Boolean, Color, Dimension, Font, Insets, Integer, Point, Rectangle,
File, Class, String, URL, Date, Properties, ListModel, and TableModel.

For all the details, see: http://bits.netbeans.org/dev/javadoc/org-openide-explorer/org/ openide/explorer/doc-files/propertyViewCustomization.html

Visual Library

The Visual Library provides predefined widgets with predefined actions, layouts, and borders. The list of predefined widgets is as follows:

For all the details, see: http://bits.netbeans.org/dev/javadoc/org-netbeans-api-visual

Dialogs

The NetBeans Dialogs API provides a number of standard dialogs for displaying standard messages for information, questions (such as “Are you sure?”, when saving), input, and error messages to the user.

Each dialog comes with a standard appearance, buttons, and icons.

NotifyDescriptor d = new NotifyDescriptor.
Message(“Text”);

NotifyDescriptor d = new NotifyDescriptor.
Confirmation(“Title”, “Text”);

’NotifyDescriptor d = new NotifyDescriptor.
InputLine(“Title”, “Text”);

Add the Dialogs API to your module and then use the table above to create dialogs as follows (in the example below, we display an information dialog):

NotifyDescriptor d = new NotifyDescriptor.Message(“Text”);
DialogDisplayer.getDefault().notify(d);

For all the details, see: http://bits.netbeans.org/dev/javadoc/org-openide-dialogs

Other Useful NetBeans APIs

org.openide.awt.HtmlBrowser.
URLDisplayer

org.openide.awt.StatusDisplayer

org.openide.util.ImageUtilities

org.openide.util.RequestProcessor

org.openide.windows.IOProvider

REUSABLE GUI COMPONENTS

In addition to the NetBeans APIs, many UI components can be used as is, simply by including the related JAR (or JARs) in your application. Normally, they also provide an API for accessing and changing their default behavior.

Component Palette, Database Explorer, Debugger, Diff Viewer, Editors (Properties, Java, XML, HTML, SQL, and more), External Browser, File Browser (Favorites Window), JavaHelp Window, Navigator Window, Options Window, Output Window, Progress Bar, Properties Window, Plugin Manager, Project System, Quick Search Field, Task List, Terminal Window, UndoRedo Manager, Validation System, and Versioning Systems (CVS, Subversion, Mercurial).

BRANDING

Everything in the NetBeans Platform can be customized to fit your specific business requirements. For example:

Icons, Look & Feel, Splash Screen, Strings (Menu Items, Title Bar, etc.)

Right-click an application in the Projects window, choose Branding, and use the Branding Editor.

NETBEANS PLATFORM GOTCHAS

The following are frequently asked questions:

NETBEANS PLATFORM ONLINE

Technical information on the NetBeans Platform is available on-line in many different forms. The most important of these are listed below:

This Refcard could not have been made without the technical insights provided by the following: Tim Boudreau, Tim Dudgeon, Jeremy Faden, Laurent Forêt, Jesse Glick, Manikantan, Ernie Rael, Antonio Vieiro and Tom Wheeler.

About The Authors

Anton Epple

Anton Epple http://eppleton.sharedhost.de/ is a NetBeans Platform consultant & trainer.

Miloš Šilhánek

Miloš Šilhánek is a Java, NetBeans Platform, 3D and AI enthusiast and Czech translator of Heiko Böck's book.

Tom Wheeler

Tom Wheeler http://www.tomwheeler.com has worked with NetBeans Platform nearly every day for the past five years and is a consultant, trainer and member of the NetBeans Dream Team.

Geertjan Wielenga

Geertjan Wielenga works on the NetBeans team and is co-author of 'Rich Client Programming: Plugging into the NetBeans Platform'

W. Heiko Böck

Heiko Böck is the author of the well-known 'The Definitive Guide to NetBeans Platform'

Andreas Stefik

Andreas Stefik is an Assistant Professor at Southern Illinois University Edwardsville.

Recommended Books

The Definitive Guide to NetBeans™ Platform is a thorough and definitive introduction to the NetBeans Platform, covering all its major APIs in detail, with relevant code examples used throughout.

---

BUY NOW

books.dzone.com/books/definitive-guide-netbeans

Rich Client Programming will help you get started with NetBeans module development, master NetBeans' key APIs, and learn proven techniques for building reliable desktop software.

---

BUY NOW

books.dzone.com/books/richclientprog