The Open APIs are the set of interfaces, defined in the package org.openide and its subpackages, and the specifications (such as for manifest files and XML layers) specified in the Open APIs Javadoc documentation. The Open APIs define how modules interface with NetBeans. The Javadoc (and the prose documentation that accompanies it) is the canonical documentation of the Open APIs. The NetBeans APIs can be broken down into a number of sections based on the roles they play, such as:

Modularity is one of the primary defining design characteristics of NetBeans—the notion that functionality should be discrete and capable of being added and removed painlessly. There is a Modules API, which defines what a module is and how to install and uninstall modules.

Modules can also offer their own APIs so that other modules can use functionality they implement. For example, the XML modules offer basic support for XML documents that can be used by other modules designed to work with specific flavors of XML. For cases like this, there is a way to declare intermodule dependencies. The NetBeans runtime will not allow a module to be installed if it requires another module that is not present; it will not allow a module to be disabled without also disabling those modules dependent on it.

In any large, extensible application, you need a way for components of the system to create objects and for other parts of the system to notice and work with them. Additionally, you need a way to present those objects to a user. Think of the example at the beginning of this chapter in which your database access UI looks a lot like your file management UI, which looks a lot like other parts of your UI. Most data formats are structured and have subcomponents, and it’s useful to be able to both manipulate and present those subcomponents as contained entities belonging to a parent entity. A generic system is needed that can nonetheless provide data-type-specific functionality.

For the first problem, creating and working with arbitrary objects, there is a convenient and understandable paradigm that arises from operating systems: files. Applications running in an operating system create files on disk and then work with them. The operating system provides the low-level services of creating and accessing files and is not interested in the content of user-created files. Modules in NetBeans are fairly analogous to applications in an operating system, and files are the core metaphor used to manage persistent objects created by modules. NetBeans has a concept of a filesystem that, in its basic sense, means a storage area or namespace into which files may be written and from which they can be read. It also has semantics by which a “file” can be a factory for Java objects.

For the second problem, presentation and containment, NetBeans provides a content-agnostic abstraction, the node, which is used to handle hierarchical representation of data and presentation of that data in arbitrary ways through a user interface. A Node is not a container for data, so much as a pointer to data. Under the hood, bridging filesystems and nodes are data objects, which identify types of data and potentially aggregate multiple related files into a single entity.

To understand filesystems in the NetBeans paradigm, you will need to stretch your concept of what a filesystem is. A filesystem in NetBeans is a place where you can hierarchically store and read files. But NetBeans does not require that a filesystem absolutely be files on a disk—only that it behave as if it were. This can be accomplished by implementing a set of interfaces defined in the Filesystems API. A filesystem need only satisfy the contract of conforming to those interfaces; how and where the data is physically stored is irrelevant and transparent to code that acts on the files.

A filesystem is effectively a hierarchical namespace for named entities that contain data or contain entities that contain data. There is a Service Provider Interface (SPI) for extending NetBeans with alternate types of file storage. As a concrete example (which will be important later in this chapter), NetBeans defines and internally uses XML filesystems which are, for all intents and purposes, analogous to physical files on disk. Additionally, there are extensions to support FTP, CVS, and other types of storage, available in separate modules that plug into NetBeans.

Once you have virtualized the concept of a filesystem, there are some other useful things you can do. If all you need to do to create a filesystem is to satisfy this contract, why not also have a virtual filesystem that owns a collection of subfilesystems and presents all of them in the same virtual namespace? NetBeans provides a concrete implementation of this in the class MultiFileSystem, part of the Filesystems API. This class allows you to construct a single namespace that merges a set of discrete subfilesystems called layers and acts as if the contents of all of them live in the same namespace (as shown in Figure 14-1). If two different layers contain a folder called /MyFolder/ with different contents, listing the contents of the MultiFileSystem’s /MyFolder/ gets you the contents of both. For dealing with name collisions (for example, two layers contain different files with the same name and path), MultiFileSystem has a stacking order of layers. In the case of a conflict, whichever filesystem is on the top of the stack is the one whose file is returned. Changes written to a MultiFileSystem are written to one or another writable layer. There are also semantics for one filesystem to mask a file that exists in another layer so that it appears not to exist even though one of the merged filesystems underneath contains it. Furthermore, it is possible to insert and remove layers at runtime.

Figure 14-1. MultiFileSystem merging constituent filesystems

NetBeans is a Java application; simply throwing around lots of files is not terribly useful. Java object instances, on the other hand, are. So NetBeans defines semantics for mapping files to Java as object instances. You can create a file with a name such as com-mycom-MyClass.instance. The Datasystems API contains a facility (implemented in a class called InstanceDataObject) to dereference a file with such a name and return an instance of the named class.

Using this infrastructure, files can be factories for Java objects. This infrastructure serves two primary purposes in NetBeans: First, it allows for modules to register objects with the system (for example, adding beans to the Component Palette or adding menu items to a menu). Second, it allows objects to be registered without the JVM actually loading the class in question unless it is actually needed, thus saving memory.

On top of this infrastructure is a facility called Lookup. Lookup adds a layer of indirection that allows module code to find objects registered via files in special folders (see Example 14.1) without dealing directly with filesystems.

As we just mentioned in the concept of an XML filesystem, the contents of the filesystem are actually represented in an XML document. In a NetBeans XML filesystem, the XML to add a Java class to a filesystem looks like Example 14-1.

<filesystem>
  <folder name="Menu">
    <folder name="View">
      <file
       name="org-netbeans-examples-quickpanel-ShowQuickPanelAction.instance"/>
    </folder>
  </folder>
</filesystem>

The effect of the preceding example is that when the system creates the main menu, it creates an instance of org.netbeans.examples.quickpanel.ShowQuickPanelAction, which supplies the icon and display name for the action on the menu, whose actionPerformed( ) method will be called if the user selects the menu item.

Not only does NetBeans use the concept of virtual filesystems for managing user files, it also uses a special virtual filesystem that contains configuration information for NetBeans itself. This is called the system filesystem. Using the convention of .instance files and other similar mechanisms to represent Java objects, NetBeans stores a wide variety of information in the system filesystem. For example, the system filesystem contains a folder called /Menu which contains subfolders with names such as File and Edit. Those subfolders in turn contain .instance files for Java classes which implement the actions that appear in the File and Edit menus. Modules are free to create their own folders in the system filesystem to store data interesting to them or add objects to folders that have defined meanings within NetBeans. One of the reasons for using the system filesystem is that it allows objects to be declared, but their classes are not actually loaded by the JVM until something needs to use them, thus saving memory. The system filesystem is the general registry for publicly accessible data and objects.

One important aspect of a NetBeans virtual filesystem is that it can fire events to notify the rest of the system when something in it changes. NetBeans listens for changes in the system filesystem, and if, for example, something creates a new .instance file in one of the menu folders, that new item will appear on the menu.

The primary way modules install their functionality into the runtime environment is via files—specifically via virtual files defined in the module’s XML filesystem layer (or module layer). This is a small XML document in the module’s JAR, conforming to the NetBeans filesystems DTD. It is declared in the module’s JAR manifest. Since NetBeans’ infrastructure allows files to actually map to Java class instances, what a module generally installs is class instances, using the .instance file convention just described. The files are put into folders in the system filesystem that have defined meanings to the system or to a module. The XML layer defines a hierarchy of files and folders which may or may not overlap with existing folders in the system filesystem. When a module is loaded, this small XML filesystem is merged with the system filesystem, shown in Figure 14-2.

Figure 14-2. Module adding XML layer to the system filesystem

Often a module needs to install objects that should be available to the runtime (such as action classes that define menu items to appear on the main menu), or to other modules (for example, services such as Java compilation). The system filesystem provides a way to do this that allows loose coupling between the modules and the system—neither the runtime nor other modules need to have been coded to anticipate the presence of these specific objects.

When a module is removed, its XML layer is cleanly extracted from the system filesystem, and the objects, menu items, services and such that it contained simply disappear from the system. For a more detailed overview of the semantics and implementation details, see Chapter 15.

Earlier we mentioned a class called MultiFileSystem, which could present a set of filesystems as if they were one—indeed, we’ve already mentioned that this is how the merging of XML layers to create the system filesystem is accomplished. But there is more to it. The system filesystem is composed of three distinct layers, which determine where settings are stored.

The system filesystem is composed of three outer layers of MultiFileSystem as follows:

The system filesystem is a MultiFileSystem containing other MultiFileSystems, as shown in Figure 14-3.

Figure 14-3. Structure of the system filesystem

To really get a sense of what lives in the system filesystem, you need to actually explore it. By default it is hidden from the Filesystems tab in Explorer. Try the following:

Figure 14-4. The system filesystem viewed from the Explorer window

The high-level view of NetBeans design is that it is a tool to edit and otherwise interact with data objects. An abstraction and Java class called DataObject exists to represent objects that contain modifiable data, and to provide ways to modify that data. DataObjects are part of the Datasystems API—modules register DataLoaders, which are responsible for creating DataObjects for files of a given type. Generally, your code will deal more with DataObjects that represent files (and provide structural programmatic access to their content), as opposed to working directly with files.

DataObjects provide the additional layer of indirection between files and Nodes; these objects identify what type of data a file contains (for example, Java source code, HTML, text, Java bytecode), and they provide ways to interact with that file appropriate to its data type. Additionally, a DataObject may be a wrapper for multiple files, such as a Java class file and a Java source file, which are in most cases more usefully treated as a single entity.

Modules install MIMEResolver s and DataLoader s. The MIMEResolvers identify a file’s MIME type (file format, for example, text/plain). The MIME type determines what DataLoader is used to create the appropriate DataObject for a given file.

The model behind NetBeans’ design can be summed up as everything is a bean. JavaBeans have properties and methods—you can read or change their properties, and ask them to do things by calling their methods. If you’ve used the NetBeans IDE, you may have noticed that most of the objects you interact with (for example, in the Explorer tree, Debugger window, or Options dialog) have property sheets to manipulate them and actions (methods) that can be called on by right-clicking them to bring up a context menu. This is the bean model in action.

As we mentioned, there is the issue of hierarchy of containment and presentation. The file metaphor solves the first piece of the equation—a common infrastructure for storing both user data files and system and session settings internal to the IDE. A filesystem is hierarchical and employs a tree structure; however, it is not flexible enough for all of the presentation and containment issues a large application is likely to face. There are times when it is desirable to restrict the files or objects that are visible, such as when the user should select a folder but not be able to select files inside folders. It is often useful to present different views of a data object, appropriate to the task the user is performing. There are cases in which you might want to present the same object as being the child of different containers, depending on the task. The semantics of a filesystem are not flexible enough to address all of these issues, and while data objects aggregate files, they are not hierarchical.

What is needed is a generic hierarchical, tree-like containment paradigm that is agnostic as to what kinds of things it is representing, and that doesn’t force any particular constraints on what can and can’t be a parent. An abstraction called nodes solves this problem.

Both user data files and objects internal to the IDE are most often represented to the user via Nodes—tree structures. Nodes are what you see rendered in the Explorer, Debugger, and Options windows, to name a few places. Almost every object you interact with in the IDE is something represented by Nodes, even if the interface to that object is not a tree-based control. Nodes are similar to JavaBeans components in that they have properties and methods. Unlike ordinary JavaBeans components, the properties and methods can change dynamically at runtime. Also, Nodes can be cut, copied, and pasted and can support context-sensitive documentation.

A Node is an object that implements the interface org.openide.nodes.Node. Nodes provide the following features:

In the course of writing your own functionality for NetBeans, you may need to create Node subclasses or instances. If the notion of writing a class that explicitly declares Node.Property objects for each property you want to expose sounds intimidating, consider using org.openide.nodes.BeanNode, a Node subclass that simply wraps any JavaBean class and presents its properties as Node.Property objects using introspection. You still have the option of a more complex implementation if that better serves your needs. Also available is org.openide.nodes.AbstractNode, an abstract base class that handles the localized display name and icon that should be exposed in the user interface. It also gives you complete flexibility with regard to implementing behavior, properties, children, and so on, while handling the more common cases with minimal required coding. The Open APIs contain many such base classes that can speed development.

An important distinction to remember is that Nodes are a presentation layer—a Node is more like a pointer to some other object, such as a DataObject representing a Java source file or a JavaBean whose properties are persistent settings the user may need to configure. A Node does not directly contain data, but exposes the properties of the underlying object and provides a way to locate interesting interfaces to interact with the data the Node represents (such as the logical structure of a Java file’s source code or an interface with a method to open that file in the editor). Nodes are not visual components; as discussed in the next section, NetBeans also provides a flexible and generic visualization toolkit for presenting Nodes in the user interface with the Explorer API.

Having a nonvisual tree structure is not useful without a way to represent it in a user interface. It is generally considered good programming practice to separate the presentation of data from the data, and NetBeans does this. Nodes provide the underlying structure, and NetBeans provides a toolkit for rendering Nodes on screen in the Explorer API. This API accomplishes two things:

The visual classes in the Explorer API can be used as they are or subclassed to modify the way data is displayed.

The abstraction of explorer views sits at the heart of NetBeans’ user interface. Many components you interact with in NetBeans are explorer views. An explorer view is a user interface component that is connected to a root node and visually renders it (and optionally its child Nodes). The window called Explorer that you see when you first start NetBeans is a window containing tabs that show explorer views rooted on different Nodes.

Many visual components in NetBeans are explorer views of one type or another—the package chooser in the New wizard, which is where you can choose to create new files; the list of breakpoints in the debugger window; and the New menu are only a few examples. Explorer views are not limited to the tree-style view you see in the main Explorer window—the Explorer API supplies a rich set of user interface components that module authors can use or subclass to display hierarchies of Nodes as menus, drop-down list components, lists, and more. Module authors can also create their own custom explorer view components, but more often it is possible to simply use the existing view components by creating custom Nodes.

For another example of the myriad uses of the Nodes and explorer views, right-click the tabs on the main window that allow you to switch workspaces. Choose Customize Workspaces from the context menu. The dialog box that pops up contains an explorer view window showing the hierarchy of workspaces. In fact, if you were to open Tools → Options → IDE Configuration → Look and Feel, you would notice a node called Workspaces with the same contents as the configuration window that just popped up—both are views of the same underlying Node.

MVC Architecture

The essence of this style of design is a paradigm called Model-View-Controller , which was first developed at Xerox’s Palo Alto Research Center in the late 1970s, and first found its way into programming in the Smalltalk language. If you have worked with Swing components, you have seen a variant of this design style. The idea is that the most flexible design for user interfaces is that what the user interacts with should be made up of three components:

A model

Encapsulates data or useful functionality or both. An example of this in NetBeans is a DataObject, which represents files that contain user-modifiable data, for example, source code.

A view

A visual component that presents the contents of the model to the user. An example of this in NetBeans is any of the classes in the org.openide.explorer.view package, which are visual classes that can display an arbitrary subsection of the nodes hierarchy in one way or another.

A controller

An object through which the view and model communicate. In NetBeans, this corresponds to nodes themselves—they are pointers to model-like objects, not containers for data in and of themselves, and an explorer view presents the underlying model to the user by presenting a hierarchy of nodes.

The result of such a design is that you get a huge amount of flexibility and code reuse. Any of the three components of MVC architecture can be replaced without the others needing to be reworked or redesigned. It is the MVC paradigm that forms the foundation of NetBeans’ architecture, as shown in Figure 14-5.

Figure 14-5. Architectural domains underlying nodes

Since NetBeans uses the nodes and bean model consistently throughout its user interface and its underlying infrastructure, you can do a surprising amount of customization without ever writing a line of code. Via the options hierarchy and the system filesystem, it is possible to substantially modify the NetBeans environment (including rendering it unusable, when it comes to the system filesystem—handle with care!).

Pasting a compiled class to a menu and executing it from there

To examine an even less common example, try the following:

1. Create a new executable Java class by choosing New → Classes → Main from the context menu of a package in Explorer → Filesystems.

2. Add the following line to its main( ) method:

   System.out.println("Hello!");

   Now compile it.

3. As in the previous examples, right-click the node for your class in the Explorer window.

4. Choose Copy from the context menu for your class’s node in the Explorer window.

5. As you did earlier, paste it into the node for the File menu in the hierarchy under Tools → Options → Paste-As-Link.

6. Now click the File menu in the main window. Your class now appears in the list of choices (see Figure 14-8). Click the menu item for it.

At this point, if it isn’t already open, the Output Window will appear, and the text Hello! will appear in it.

Figure 14-8. The File menu with a custom executable class added to it

A module literally provides additional classes that do something useful. Via its manifest, a module describes how to load these classes and use them in NetBeans. By and large, modules add functionality by adding entries to the system filesystem, just as pasting an element into the Menu Bar subfolder under Tools → Options creates an additional menu item. So, on encountering an unknown JAR file in the modules subdirectory on startup, NetBeans examines its manifest file, and looks for entries such as:

Manifest-Version: 1.0
OpenIDE-Module: org.netbeans.modules.autoupdate/1
OpenIDE-Module-Localizing-Bundle: org/netbeans/modules/autoupdate/
 Bundle.properties
OpenIDE-Module-Layer: org/netbeans/modules/autoupdate/
 resources/mf-layer.xml
OpenIDE-Module-Install: org/netbeans/modules/autoupdate/
 AutoUpdateModule.class
OpenIDE-Module-IDE-Dependencies: IDE/1 > 1.28
OpenIDE-Module-Module-Dependencies: org.netbeans.core/1 > 1.0
OpenIDE-Module-Specification-Version: 1.7
OpenIDE-Module-Implementation-Version: 200111231643

Name: org/netbeans/modules/autoupdate/NbmDataLoader.class
OpenIDE-Module-Class: Loader

to tell it what to do with the contents of this JAR file. For an explanation of the module manifest format, see Chapter 15.

A module actually does not have to have an installer class for the IDE to load it. A module’s manifest can specify an XML layer file packaged inside it (in its JAR file), which declares what objects should be created, and where. Where possible, using layers is the preferred way to have your module install itself.

This is actually quite simple—a module needs to include in its manifest a line such as

OpenIDE-Module-Layer: org/netbeans/modules/autoupdate/resources/mf-layer.xml

The path specified here is a path to the layer XML file within the module JAR file. NetBeans will extract the specified XML file when your module is loaded and merge it into the system filesystem. The syntax of a layer is fairly simple—the filesystem element contains a set of folder and file elements that make a small virtual filesystem. A top-level XML element called filesystem can contain the subelements folder and file, and folder elements can then contain additional folder and file elements. folder and file elements can have attributes and also can have either CDATA sections specifying their content, or have a URL property that points to what should appear to be the content of the file. The contents of the virtual filesystem, declared in XML, are the module’s “layer.”

There is no fixed description for what a module can do. Part of the purpose and strength of a tools platform with generic APIs is to leave as much choice as possible up to the module author. Essentially, anything you can do in Java is possible, from building support for Perl with syntax highlighting and GUI design, to adding debuggers, tools for deploying classes to an application server, code profilers, UML tools, jargonizers, a Tetris game, or a full-blown office productivity suite!

So, in summary:

Modules can also be dynamically loaded and unloaded by disabling them in Tools → Options → IDE Configuration → System → Modules. For example, try the following:

Notice that the GUI Editing workspace immediately disappears—and the Form Editor closes. Also notice, you now have two files listed in Explorer—one of them with the extension .form (the form editor stores GUI design data in this XML file and causes it to be hidden in the explorer). If you reenable the module, the Form Editor menu item will reappear in the View menu, and you will once again be able to work with forms.

What has actually happened is that the IDE has unloaded the classes provided by the module from memory, removed any objects the module specifies that the IDE should add to the system filesystem via its manifest, and called the module’s uninstalled( ) method if the module specified an installer class in its manifest to perform any additional cleanup. The result is that the next time NetBeans is started, it will no longer use the module JAR file.

Deleting module files means that they do not get the chance to clean up after themselves. The result can be exceptions and unpredictable behavior. Also, bear in mind that there are cases of module interdependencies. NetBeans has built-in protection against disabling modules on which other modules have dependencies. Deleting modules short-circuits this protection. Don’t do it! While future versions of NetBeans will have support for physically deleting modules, manually deleting their files is never a good idea.

It’s all well and good to talk about modules in the abstract; however, the following experiment will give you a tangible sense of just how modular the NetBeans IDE is:

What comes up is an application with almost no features. You get an Explorer window with a tree view of files. Note that you now see both .java and .class files separately in Explorer, whereas, if the Java module were installed, they would be aggregated as a single node. With this instance of NetBeans, you can only cut and paste files—it is a glorified file browser, and little else.

While this is not the most useful way to run the NetBeans IDE, it truly makes the point of just how modular NetBeans is!

For a simple example of interacting directly with NetBeans’ runtime via internal execution, let’s try creating a small class which will write to the status bar in the main window. Create the class shown in Example 14-2.

import org.openide.TopManager;
public class StatusWriter {
  public static void main(String args[ ]) {
    TopManager.getDefault( ).setStatusText("Hello world!");
  }
}

Set the class to use Internal Execution and run it (press F6). You will see the text of the status bar change to Hello World!

Let us change this code to do something marginally more useful—change the current workspace in the running IDE. Edit the class file you created before and replace the line that prints Hello with the following:

TopManager.getDefault( ).getWindowManager( ).findWorkspace("Debugging").activate( );

Recompile your class and execute it. The current set of windows disappears, and you have changed to the Debugging workspace (to get back to the editor, simply click the Editing tab at the bottom of the main IDE window).

As you can see, quite a bit is going on under the hood of NetBeans. For testing and experimentation, basic functionality can be accessed fairly simply using internal execution. NetBeans is a complex piece of software, but it provides well-defined contracts for adding components via the Open APIs. Next we will examine those APIs in detail, so that you can begin to understand how the various pieces that make up an application built on NetBeans interoperate.