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
These are the most important NetBeans-related manifest attributes.
| Type |
Description |
| OpenIDE-Module |
The identifier of a module, providing a unique name used for recognition by the module system. This is the only required entry in a manifest file for a module. |
| OpenIDE-Module-Layer |
The location and name of the module's layer.xml file, if any. |
| OpenIDE-Module-Public-Packages |
By default, all packages in a module are hidden from all other modules. Via this attribute, you expose packages to external modules. |
| OpenIDE-Module-Localizing-Bundle |
The location and name of a properties file providing a display name and the like. |
| OpenIDE-Module-Module-Dependencies OpenIDE-Module-Java-Dependencies |
Modules can request general or specific versions of other modules (|OpenIDE-Module-Module-Dependencies|), Java packages (|OpenIDE-Module-Package-Dependencies|), or Java itself (|OpenIDE-Module-Java-Dependencies|). |
| OpenIDE-Module-Provides OpenIDE-Module-Requires |
Modules can specify dependencies without naming the exact module to depend on. A module may /provide/ one or more /tokens/. These are strings of conventional meaning, in the format of a Java package or class name. |
| OpenIDE-Module-Specification-Version OpenIDE-Module-Implementation-Version |
In line with the Java Versioning Specification, modules can indicate two pieces of version information about themselves using the |OpenIDE-Module-Specification-Version| and the |OpenIDE-Module-Implementation-Version| tags. |
| AutoUpdate-Show-In-Client |
This attribute determines whether the module is shown in the Plugin Manager. |
For details on these and other attributes, see
http://bits.netbeans.org/6.8/javadoc/org-openide-modules.
To influence the lifecycle of a module, extend org.openide.modules.ModuleInstall, and register it in the manifest under the OpenIDE-Module-Install key.
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.
| Type |
Description |
| TopComponent |
A JPanel that provides a new window in your application. The window comes with many features for free, such as maximize/minimize and dock/undock. |
| Mode |
A container in which TopComponents are docked. You do not need to subclass this class to use it. Instead, it is configured in an XML file. |
| TopComponentGroup |
A group of windows, which should behave in concert. For example, windows within a group can be opened or closed together. As with Modes, these are defined in an XML file, not by subclassing TopComponentGroup. |
| WindowManager |
Controls all the windows, modes, and window groups. You can request the WindowManager for its windows, modes, and groups. You can also cast it to a JFrame and then set the title bar and anything else that you would do with JFrames. |
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:
| Type |
Description |
| editor |
main area of application (not necessarily an actual editor |
| explorer |
left vertical area, such as for a Projects window |
| properties |
right vertical area, typically for a Properties window |
| navigator |
left lower vertical area |
| output |
horizontal area at base of application |
| palette |
right vertical area for items to drag into a visual pane |
| leftSlidingSide |
minimized state in left sidebar |
| rightSlidingSide |
minimized state in right sidebar |
| bottomSlidingSide |
minimized state in bottom status area |
A TopComponent is registered in a mode as follows, note especially the lines in bold below:
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
Hide the existing modes and create your own, if the existing ones are really not sufficient for you.
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:
| How do I... |
Description |
| Find a specific TopComponent? |
WindowManager.getDefault().findTopComponent('id') |
| Find a specific mode? |
WindowManager.getDefault().findMode('id')Once you have found a mode, you can use Mode.dockInto(tc)to programmatically dock a TopComponent into a specific mode. |
| Find a specific TopComponentGroup? |
WindowManager.getDefault().findTopComponent Group('id') |
| Ensure that the application is fully started up? |
WindowManager.getDefault().invokeWhenUIReady(Runnable) |
| Get the active TopComponent? |
WindowManager.getDefault().getRegistry().getActivated() |
| Get a set of opened TopComponents? |
WindowManager.getDefault().getRegistry().getOpened() |
| Get the main frame of the application |
WindowManager.getDefault().getMainWindow() |
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:
| Type |
Description |
| Global lookup, provides selection management |
The Lookup that gives you access to the currently selected UI component, most commonly the focused Node.Lookup lkp = Utilities.actionsGlobalContext(); |
| Local lookup, provides lookup of NetBeans objects such as windows and Nodes |
The local context of a specific NetBeans Platform UI object. //For Windows components: Lookup lkp = myTopComponent,getLookup(); //For Nodes: Lookup lkp = myNode.getLookup(); |
| Default lookup |
The application's context, comparable to the JDK 6 ServiceLoader class, provided via the META-INF/services folder. Lookup lkp = Lookup.getDefault(); |
These are typical tasks related to Lookup and how to code them:
| How do I... |
Description |
| Register a service? |
Annotate a service provider with the @ServiceProvider class annotation, at compile time the METAINF/ services folder is created, registering the implementation. |
| Find the default service implementation? |
MyService svc = Lookup.getDefault().lookup(MyService.class) |
| Find all service implementations? |
Collection<? extends MyService> coll = Lookup.getDefault(). lookupAll(MyService.class) |
| Listen to changes in a Lookup?Tip: Keep a reference to the result object, otherwise it will be garbage collected. |
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 } ); lkpResult.allInstances(); // first call is needed |
| Create a Lookup for an object? |
//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); |
| Merge Lookups? |
Lookup commonlkp = new ProxyLookup( dataObjectLookup, nodeLookup, dynamicLookup); |
| Provide a Lookup for my TopComponent? |
//In the constructor of TopComponent: associateLookup(myLookup); |
| Provide a Lookup for a subclass of AbstractNode? |
new AbstractNode(myKids, myLookup); |
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:
| java.io.File |
org.openide.filesystems.FileObject |
| Create with a constructor |
Get from the FileSystem |
| Can represent something that doesn't exist, such as new File('some/place/that/doesnt/exist') |
Typically represents something that exists |
| Cannot listen to changes |
FileChangeListener listens to changes to FileObject, as well as anything beneath the FileObject |
| Represents a file on disk |
Not necessarily a file on disk, could be in a database, FTP server, virtual, or anywhere else |
| No attributes |
Can have attributes, which are key-value pairs associated with a FileObject |
Converting between common data types:
| How do I get... |
Description |
| a java.io.File for a FileObject? |
FileUtil.toFile(FileObject fo) |
| a FileObject for a File? |
FileUtil.toFileObject(File f) |
| a DataObject for a FileObject? |
DataObject.find (theFileObject) |
| a FileObject for a DataObject? |
theDataObject.getPrimaryFile() |
| a Node for a DataObject? |
theDataObject.getNodeDelegate() |
| a DataObject for a Node? |
DataObject dob = (DataObject) theNode.getLookup().lookup (DataObject.class); if (dob != null) { //do something } |
| a reference to the System FileSystem? |
//Get the root: FileUtil.getConfigRoot() //Get a specific folder: FileUtil.getConfigFile('path/to/my/folder') |
The NetBeans Platform provides a number of custom URLs for accessing things.
| jar |
For representing entries inside JARs and ZIPs, including the root directory entry |
| nbres |
A resource loaded from a NetBeans module, e.g. nbres:/org/netbeans/modules/foo/resources/foo.dtd |
| nbresloc |
Same, but transparently localized and branded according to the usual conventions, e.g. nbresloc:/org/netbeans/modules/foo/resources/foo.html may actually load the same thing as nbres:/org/netbeans/modules/foo/resources/foonbja.html. |
| nbinst |
Loads installation files using InstalledFileLocator in installation directories, e.g. nbinst:///modules/ext/some-lib.jar may load the same thing as file:/opt/netbeans/ide4/modules/ext/some-lib.jar. |
| nbfs |
Refers to a file object in the System FileSystem (XML layers). For example, nbfs:/SystemFileSystem/Templates/Other/html.html refers to an HTML file template installed in the IDE> |
Actions
Actions are pieces of code that are invoked when the user presses a menu item, toolbar button, or keyboard shortcut.
| Type |
Description |
| Actions.alwaysEnabled |
An action that is always enabled. Typically, use this for 'File > Open' actions, for example. |
| Actions.context |
An action that is bound to a context. If an action should only be enabled under certain conditions, use this action. |
| Actions.callback |
An action with an assigned key used to find a delegate in the ActionMap of the active component. |
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:
Actions.context:
Actions.callback:
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.
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
Toolbar Buttons
Shortcuts
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:
| Type |
Description |
| Node |
Base class for representing business objects to the user. |
| AbstractNode |
The usual base class for Node implementations. |
| DataNode |
Specialized Node class for wrapping a file and displaying it as a Node to the user. |
| BeanNode |
Specialized Node class that wraps a JavaBean and presents it to the user as a Node. It also provides simplistic access to property sheets. |
| FilterNode |
Specialized Node class that decorates an existing Node by adding/removing features to/from it. |
A Node is a container for its own child Nodes. These classes create child Nodes:
| ChildFactory |
Factory for creating child Nodes. Optionally, these can be created asynhronously, that is, when the user expands the Node. |
| Children.Keys |
Older version of ChildFactory. You should be able to replace any implementation of Children.Keys with ChildFactory. |
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.
| Type |
Description |
| Scene |
Provides the root element of the hierarchy of displayed widgets. |
| LayerWidget |
Provides a transparent surface, comparable to a JGlassPane. |
| ComponentWidget |
Provides a placeholder widget for AWT/Swing components. |
| ImageWidget |
Provides images to the scene. |
| LabelWidget |
Provides a label as a widget. |
| IconNodeWidget |
Provides an image and a label. |
| ConnectionWidget |
Provides connections between widgets, with anchors, control poins, and end points. |
| ConvolveWidget |
Provides coil/twist effect, i.e., a convolve filter to a child element. |
| LevelOfDetailsWidget |
Provides a container for widgets, with visibility and zoom features. |
| ScrollWidget/SwingScrollWidget |
Provides a scrollable area, with/ without JScrollBar as scroll bars. |
| SeparatorWidget |
Provides a space with thickness and orientation. |
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.
| Type |
Description |
| Information Dialog |
NotifyDescriptor d = new NotifyDescriptor.Message('Text'); |
| Question Dialog |
NotifyDescriptor d = new NotifyDescriptor.Confirmation('Title', 'Text'); |
| Input Dialog |
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):
For all the details, see http://bits.netbeans.org/6.8/javadoc/org-openide-dialogs.
The Dialogs API also provides a group of Wizard classes for multipage dialogs!
Other Useful NetBeans APIs
| Type |
Description |
| org.apache.tools.ant.module.api.support.ActionUtils |
Used for running Ant targets. |
| org.openide.util.ImageUtilities |
Provides useful static methods for manipulation with images/icons, results are cached |
| org.openide.awt.HtmlBrowser.URLDisplayer |
Displays URLs, opens browsers, distinguishes embedded vs. external browsers. |
| org.netbeans.api.progress.ProgressHandle |
Integrates visualization of long running tasks with the NetBeans Platform progress bar. |
| org.openide.util.RequestProcessor |
Performs asynchronous threads in a dedicated thread pool. |
| org.openide.awt.UndoRedo |
Listens to editing changes and activates the 'Undo' and 'Redo' buttons. |
Explore the Utilities API (org.openide.util.jar) for many useful classes that all NetBeans Platform applications can use.
