The NetBeans Platform is a generic framework for commercial and open source desktop Swing applications. It provides the 'plumbing' that you would otherwise need to write yourself, such as the code for managing windows, connecting actions to menu items, and updating applications at runtime. The NetBeans Platform provides all of these out of the box on top of a reliable, flexible, and well-tested modular architecture.Vaadin is a server-side Ajax web application development framework that allows you to build web applications just like with traditional desktop frameworks, such as AWT or Swing. An application is built from user interface components contained hierarchically in layout components.

In this ref card, 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.

To get started with the NetBeans Platform:

Join the NetBeans Community mailing lists!

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

The NetBeans Platform consists of a large set of modules. You do not need all of them. In fact, you only need 5. You also do not need to have a user interface, meaning that you can create server/console applications on the NetBeans Platform.

The complete list of NetBeans Platform modules is provided below. Items in red are mandatory, items in green are optional.

Some of the items in the list above can be used outside of the NetBeans Platform. In these cases, you can put the JAR on the class path of a standard Swing application and use the related functionality there: org-openide-filesystems.jar (to use the virtual filesystem), org-openide-util.jar (to use the Lookup class), org-openide-nodes.jar & org-openide-explorer.jar (to use Nodes and explorer views), org-netbeans-swing-outline.jar (to use a Swing treatable component), org-netbeans-api-visual.jar (to use the widget library).

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

Module System

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.

For details on these and other attributes, see

http://bits.netbeans.org/6.8/javadoc/org-openide-modules.

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 System FileSystem via registration

entries in the layer.xml file. The NetBeans Platform provides a set of default modes, the most important of which are as follows:

A TopComponent is registered in a mode as follows, note especially the lines in bold below:

<folder name='Windows2'>
<folder name='Components'>
<file name='MyTopComponent.settings' url='MyTopComponentSettings.xml'/>
</folder>
<folder name='Modes'>
<folder name='editor'>
<file name='MyTopComponent.wstcref' url='MyTopComponentWstcref.xml'/>
</folder>
</folder>
</folder>

The XML files referred to above are small settings files that NetBeans IDE can generate for you.

Though the default modes should be sufficient for most business scenarios, you might like to adjust them. In that case,you are creating your own mode definitions. A mode definition must follow the related DTD, which is as follows:

http://netbeans.org/dtds/mode-properties2_1.dtd

The window manager handles the display of the windows in the application's main frame. Aside from being able to access its main Frame, you can also query it for information, as listed below:

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) enabling 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:

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, Navigator/Panels, OptionsDialog, Services, Shortcuts, TaskList, and Windows2.

The NetBeans Platform helps you to register items correctly in the file system by letting you, in some cases, annotate your classes instead of requiring you to manually type XML tags in the layer.xml file by hand. The current set of annotations impacting the layer.xml is listed below:

@AntBasedProjectRegistration, @CompositeCategoryProvider.Registration, @EditorActionRegistration,@LookupMerger.Registration, @LookupProvider.Registration, @NodeFactory.Registration, @OptionsPanelController.ContainerRegistration, @OptionsPanelController.SubRegistration, @OptionsPanelController.TopLevelRegistration, @ProjectServiceProvider, @ServiceProvider, @ServicesTabNodeRegistration

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:

The NetBeans Platform provides a number of custom URLs for accessing things.

Actions

Actions are pieces of code that are 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 your standard JDK

actions (AbstractAction, ActionListener, etc) in any way. Instead, you need to bind them to one of the classes listed above, using the layer.xml file to do so.

Actions.alwaysEnabled:

<file name='your-pkg-action-id.instance'>
   <attr name='instanceCreate'
        methodvalue='org.openide.awt.Actions.alwaysEnabled'/>
   <attr name='delegate'
        methodvalue='your.pkg.YourAction.factoryMethod'/>
   <attr name='displayName' bundlevalue='your.pkg.Bundle#key'/>
   <attr name='iconBase' stringvalue='your/pkg/YourImage.png'/>
<!-- if desired: <attr name='noIconInMenu' boolvalue='false'/>
<!-- if desired <attr name='asynchronous' boolvalue='true'/>
</file>

Actions.context:

<file name='action-pkg-ClassName.instance'>
   <attr name='instanceCreate'
      methodvalue='org.openide.awt.Actions.context'/>
   <attr name='type' stringvalue='org.netbeans.api.actions.Openable'/>
   <attr name='selectionType' stringvalue='ANY'/> (or EXACTLY_ONE)
   <attr name='delegate' newvalue='action.pkg.YourAction'/>
   <attr name='key' stringvalue='KeyInActionMap'/>
   <attr name='surviveFocusChange' boolvalue='false'/>
   <attr name='displayName' bundlevalue='your.pkg.Bundle#key'/>
   <attr name='iconBase' stringvalue='your/pkg/YourImage.png'/>
   <!-- if desired: attr name='noIconInMenu' boolvalue='false'/>
   <!-- if desired: <attr name='asynchronous' boolvalue='true'/>
</file>

Actions.callback:

<ile name='action-pkg-ClassName.instance'>
   <attr name='instanceCreate'
      methodvalue='org.openide.awt.Actions.callback'/>
   <attr name='key' stringvalue='KeyInActionMap'/>
   <attr name='surviveFocusChange' boolvalue='false'/>
   <attr name='fallback' newvalue='action.pkg.DefaultAction'/>
   <attr name='displayName' bundlevalue='your.pkg.Bundle#key'/>
    <attr name='iconBase' stringvalue='your/pkg/YourImage.png'/>
    <!-- if desired: <attr name='noIconInMenu' boolvalue='false'/>
    <!-- if desired: <attr name='asynchronous' boolvalue='true'/>
</file>

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

An action is registered in the layer.xml file in the 'Actions' folder, within a folder reflecting its place in the action pool.

<folder name='Actions'>
     <folder name='Window'>
        <file name='your-pkg-action-id.instance'>
               ...
       </file>
   </folder>
</folder>

Depending on your business requirements, once you have actions registered in the layer.xml file, you need to bind them to menu items, toolbar buttons, and keyboard shortcuts.

Menu Items

<folder name='Menu'>
    <folder name='Window'>
        <file name='your-pkg-action-id.shadow'>
             <attr name='originalFile' stringvalue='Actions/Window/
             your-pkg-action-id.instance'/>
             <attr name='position' intvalue='50'/>
        </file>
   </folder>
</folder>

Toolbar Buttons

<folder name='Toolbars'>
    <folder name='Window'>
        <file name='your-pkg-action-id.shadow'>
            <attr name='originalFile' stringvalue='Actions/Window/
             your-pkg-action-id.instance'/>
            <attr name='position' intvalue='50'/>
        </file>
    </folder>
</folder>

Shortcuts

<folder name='Shortcuts'>
   <file name='M.shadow'>
       <attr name='originalFile'
   stringvalue='Actions/Edit/org-netbeans-modules-
  some-MyAction.instance'/>
  </file>
   <file name='D-M.shadow'>
      <attr name='originalFile'
         stringvalue='Actions/Edit/org-netbeans-modules
           some-CtrlMyAction.instance'/>
  </file>
   <file name='O-M.shadow'>
      <attr name='originalFile'
         stringvalue='Actions/Edit/org-netbeans-modules
           some-AltMyAction.instance'/>
  </file>
</folder>

As key code, use KeyEvent.VK_keycode without VK_ prefix, as described in Javadoc of org.openide.util.Utilities stringToKey() and keyToString() methods.

Nodes

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, and actions. The list of Nodes is below, which you can use as is or extend as needed:

A Node is a container for its own child Nodes. These classes create child Nodes:

Children.Array, Children.Map, Children.SortedArray, Children.SortedMap: These classes are less frequently used and are no longer well supported.

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

Explorer Views

Visual Library

The NetBeans visual library is a generic widget and graph library, providing a collection of predefined widgets that integrate well with other NetBeans Platform objects, such as Nodes and windows. Below is the list of widgets provided by this library.

For all the details, see http://bits.netbeans.org/6.8/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.

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/6.8/javadoc/org-openide-dialogs.

Other Useful NetBeans APIs

The following are frequently asked questions, returning over and over again, with their answers:

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.